SERP organic Google thông thường trực tiếp
DataForSEO
SEO, search-engine results, keyword research, backlinks and AI visibility data.
SERP organic Google thông thường trực tiếp
Trả về kết quả xếp hạng cho một từ khóa trên Google, đồng bộ. Trả về keyword, type, se_domain, location_code, language_code, check_url, datetime, spell, refinement_chips, item_types, items_count và items. Được bọc trong phong bì của DataForSEO: dữ liệu ở tasks[0].result, kết quả ở tasks[0].status_code - yêu cầu bị từ chối vẫn trả về HTTP 200.
Tham chiếu giá
- Đo lường: Chi phí phản hồi được báo cáo.
- Ước tính tham chiếu cho mỗi yêu cầu: USD 0.008.
- Hệ số khách hàng tham chiếu: 1.0. Không áp dụng lại cho số tiền khách hàng đã quyết toán.
Chỉ là siêu dữ liệu tham chiếu, không phải báo giá cho tài khoản, mức giá được bảo đảm hay hạn mức chi tiêu. Tín dụng tài nguyên không phải tín dụng Felo. Khoản phí cuối cùng tuân theo bản ghi thanh toán của Felo.
- Kiểu: array (object | null)[]
- depthKiểu: integer | null
độ sâu phân tích
trường tùy chọn
số kết quả trong SERP
giá trị mặc định:
10giá trị tối đa:
200
Tài khoản của bạn sẽ bị tính phí cho mỗi SERP chứa tối đa 10 kết quả;Đặt độ sâu trên 10 có thể phát sinh phí bổ sung nếu công cụ tìm kiếm trả về hơn 10 kết quả;
Chi phí có thể được tính trên trang Bảng giá.
- deviceKiểu: string | null
loại thiết bị
trường tùy chọn
trả về kết quả cho một loại thiết bị cụ thể
có thể nhận các giá trị:
desktop,mobilegiá trị mặc định:
desktop - findKiểu: array string[] | null
_targets _in các loại phần tử SERP cần kiểm tra mục tiêu
trường tùy chọn
để bật tham số này,
stop_crawl_on_matchcũng phải được bậtchỉ định những loại phần tử SERP cần kiểm tra để khớp mục tiêu
nếu không được chỉ định, tất cả phần tử cấp đầu tiên có trường
urlvàdomainđều được kiểm tra mục tiêugiá trị khả dụng:
organic,paid,local_pack,featured_snippet,events,google_flights,images,jobs,knowledge_graph,local_service,map,scholarly_articles,third_party_reviews,twitterLưu ý: không được chứa cùng loại phần tử như
ignore_targets_inví dụ:
"find_targets_in": ["organic", "featured_snippet"]tìm hiểu thêm về tham số này trên Trung tâm trợ giúp
- groupKiểu: boolean | null
_organic _results hiển thị kết quả liên quan
trường tùy chọn
nếu đặt thành
true, phần tửrelated_resulttrong phản hồi sẽ được cung cấp dưới dạng đoạn trích của kết quả organic gốc;nếu đặt thành
false, phần tửrelated_resultsẽ được cung cấp dưới dạng một kết quả organic riêng;giá trị mặc định:
true - ignoreKiểu: array string[] | null
_targets _in các loại phần tử SERP cần loại trừ khỏi tìm kiếm mục tiêu
trường tùy chọn
để bật tham số này,
stop_crawl_on_matchcũng phải được bậtchỉ định những loại phần tử SERP cần loại trừ khi tìm kiếm mục tiêu khớp
giá trị khả dụng:
organic,paid,local_pack,featured_snippet,events,google_flights,images,jobs,knowledge_graph,local_service,map,scholarly_articles,third_party_reviews,twitterLưu ý: không được chứa cùng loại phần tử như
find_targets_inví dụ:
"ignore_targets_in": ["paid", "images"]tìm hiểu thêm về tham số này trên Trung tâm trợ giúp
- keywordKiểu: string
từ khóa
trường bắt buộc
bạn có thể chỉ định tối đa 700 ký tự trong trường
keywordmọi %## sẽ được giải mã (ký tự '+' sẽ được giải mã thành ký tự khoảng trắng)
nếu bạn cần dùng ký tự "%" cho
keyword, hãy chỉ định là "%25";nếu bạn cần dùng ký tự “+” cho
keyword, hãy chỉ định là “%2B”;nếu trường này chứa các tham số như 'allinanchor:', 'allintext:', 'allintitle:', 'allinurl:', ‘cache:’, 'define:', 'filetype:', 'id:', 'inanchor:', 'info:', 'intext:', 'intitle:', 'inurl:', 'link:', 'site:', phí mỗi tác vụ sẽ được nhân với 5
- languageKiểu: string
_code mã ngôn ngữ của công cụ tìm kiếm
trường bắt buộc nếu bạn không chỉ định
language_namenếu bạn dùng trường này, bạn không cần chỉ định
language_namebạn có thể nhận danh sách ngôn ngữ khả dụng của công cụ tìm kiếm với
language_codebằng cách gửi một yêu cầu riêng đếnhttps://api.dataforseo.com/v3/serp/google/languagesví dụ:
en - languageKiểu: string
_name tên đầy đủ của ngôn ngữ công cụ tìm kiếm
trường bắt buộc nếu bạn không chỉ định
language_codenếu bạn dùng trường này, bạn không cần chỉ định
language_codebạn có thể nhận danh sách ngôn ngữ khả dụng của công cụ tìm kiếm với
language_namebằng cách gửi một yêu cầu riêng đếnhttps://api.dataforseo.com/v3/serp/google/languagesví dụ:
English - locationKiểu: integer
_code mã vị trí của công cụ tìm kiếm
trường bắt buộc nếu bạn không chỉ định
location_namehoặclocation_coordinatenếu bạn dùng trường này, bạn không cần chỉ định
location_namehoặclocation_coordinatebạn có thể nhận danh sách vị trí khả dụng của các công cụ tìm kiếm cùng
location_codebằng cách gửi một yêu cầu riêng đếnhttps://api.dataforseo.com/v3/serp/google/locationsví dụ:
2840 - locationKiểu: string
_coordinate tọa độ GPS của một vị trí
trường bắt buộc nếu bạn không chỉ định
location_namehoặclocation_codenếu bạn dùng trường này, bạn không cần chỉ định
location_namehoặclocation_codeTham số
location_coordinatephải được chỉ định ở định dạng "latitude,longitude,radius"số chữ số thập phân tối đa cho "latitude" và "longitude": 7
giá trị tối thiểu cho "radius": 199 (mm)
giá trị tối đa cho "radius": 199999 (mm)
ví dụ:
53.476225,-2.243572,200 - locationKiểu: string
_name tên đầy đủ của vị trí công cụ tìm kiếm
trường bắt buộc nếu bạn không chỉ định
location_codehoặclocation_coordinatenếu bạn dùng trường này, bạn không cần chỉ định
location_codehoặclocation_coordinatebạn có thể nhận danh sách vị trí khả dụng của công cụ tìm kiếm cùng
location_namebằng cách gửi một yêu cầu riêng đếnhttps://api.dataforseo.com/v3/serp/google/locationsví dụ:
London,England,United Kingdom - matchKiểu: string
_type kiểu khớp mục tiêu
trường bắt buộc nếu
stop_crawl_on_matchđược chỉ địnhkiểu khớp cho
match_valuegiá trị khả dụng:
domain– miền hoặc miền con cụ thểwith_subdomains– miền chính và các miền conwildcard– mẫu đại diện - matchKiểu: string
_value miền, miền con hoặc giá trị đại diện mục tiêu
trường bắt buộc nếu
stop_crawl_on_matchđược chỉ địnhchỉ định miền, miền con hoặc giá trị đại diện mục tiêu;
Lưu ý: miền hoặc miền con phải được chỉ định không kèm giao thức yêu cầu;
ví dụ:
"match_value": "dataforseo.com","match_value": "/blog/post-*" - maxKiểu: integer | null
_crawl _pages giới hạn thu thập trang
trường tùy chọn
số trang kết quả tìm kiếm cần thu thập
giá trị tối đa:
100Lưu ý: bạn sẽ bị tính phí cho mỗi trang được thu thập (10 kết quả organic mỗi trang);
tìm hiểu thêm về giá trên trang Bảng giá của chúng tôi;
Lưu ý #2: các tham số
max_crawl_pagesvàdepthbổ sung cho nhau;tìm hiểu thêm tại trung tâm trợ giúp của chúng tôi
- osKiểu: string | null
hệ điều hành thiết bị
trường tùy chọn
nếu bạn chỉ định
desktoptrong trườngdevice, hãy chọn từ các giá trị sau:windows,macosgiá trị mặc định:
windowsnếu bạn chỉ định
mobiletrong trườngdevice, hãy chọn từ các giá trị sau:android,iosgiá trị mặc định:
android - seKiểu: string | null
_domain tên miền công cụ tìm kiếm
trường tùy chọn
chúng tôi tự động chọn tên miền công cụ tìm kiếm phù hợp theo vị trí và ngôn ngữ bạn chỉ định
tuy nhiên, bạn có thể đặt tên miền công cụ tìm kiếm tùy chỉnh trong trường này
ví dụ:
google.co.uk,google.com.au,google.de, v.v. - searchKiểu: string | null
_param tham số bổ sung của truy vấn tìm kiếm
trường tùy chọn
lấy danh sách các tham số khả dụng và thông tin chi tiết bổ sung tại đây
Lưu ý: các tham số công cụ tìm kiếm sau không được hỗ trợ và sẽ tự động bị bỏ đặt nếu được chỉ định:lr,cr,as_qdr,as_sitesearch,as_occt,as_filetype. - stopKiểu: array (object | null)[] | null
_crawl _on _match mảng các mục tiêu để dừng thu thập dữ liệu trường tùy chọn nếu được chỉ định, phản hồi sẽ chứa kết quả SERP đến và bao gồm match_value đã chỉ định; bạn có thể chỉ định tối đa 10 giá trị mục tiêu trong mảng này ví dụ: "stop_crawl_on_match":[{"match_value":"dataforseo.com","match_type":"with_subdomains"}] tìm hiểu thêm về tham số này trên Trung tâm trợ giúp của chúng tôi - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api Tài khoản của bạn sẽ bị tính phí cho mỗi SERP được thu thập qua các mục tiêu đã chỉ định
- matchKiểu: string | null
_type loại khớp mục tiêu trường bắt buộc nếu stop_crawl_on_match được chỉ định; loại khớp cho match_value giá trị khả dụng: domain, with_subdomains, wildcard
- matchKiểu: string | null
_value miền mục tiêu hoặc giá trị ký tự đại diện trường bắt buộc nếu stop_crawl_on_match được chỉ định; chỉ định miền mục tiêu hoặc giá trị ký tự đại diện; Lưu ý: tên miền phải được chỉ định không có giao thức yêu cầu; ví dụ: dataforseo.com
- tagKiểu: string | null
mã định danh tác vụ do người dùng xác định
trường tùy chọn
giới hạn ký tự là 255
bạn có thể dùng tham số này để nhận diện tác vụ và khớp với kết quả
bạn sẽ thấy giá trị
tagđã chỉ định trong đối tượngdatacủa phản hồi - targetKiểu: string | null
miền, miền con hoặc trang web mục tiêu cần lấy kết quả
trường tùy chọn
miền hoặc miền con phải được chỉ định không kèm
https://vàwww.lưu ý rằng kết quả của các tác vụ dành riêng cho
targetsẽ chỉ bao gồm các phần tử SERP chứa chuỗiurl;bạn cũng có thể dùng ký tự đại diện (‘*’) để chỉ định mẫu tìm kiếm trong SERP và thu hẹp kết quả;
ví dụ:
example.com- trả về kết quả cho trang chủ của website với các URL nhưhttps://example.com, hoặchttps://www.example.com/, hoặchttps://example.com/;example.com*- trả về kết quả cho miền, bao gồm tất cả các trang của miền;*example.com*- trả về kết quả cho toàn bộ miền, bao gồm tất cả các trang và miền con;*example.com- trả về kết quả cho trang chủ bất kể miền con, nhưhttps://en.example.com;example.com/example-page- trả về kết quả cho URL chính xác;example.com/example-page*- trả về kết quả cho tất cả URL của miền bắt đầu bằng chuỗi đã chỉ định - targetKiểu: string | null
_search _mode chế độ khớp mục tiêu
trường tùy chọn
để bật tham số này,
stop_crawl_on_matchcũng phải được bậtxác định cách dừng thu thập khi nhiều mục tiêu được chỉ định trong
stop_crawl_on_matchgiá trị khả dụng:
all,anyall– quá trình thu thập chỉ dừng khi tìm thấy tất cả mục tiêu đã chỉ địnhany– quá trình thu thập dừng khi tìm thấy bất kỳ mục tiêu nàogiá trị mặc định:
anytìm hiểu thêm về tham số này trên Trung tâm trợ giúp của chúng tôi
- urlKiểu: string | null
URL trực tiếp của truy vấn tìm kiếm
trường tùy chọn
bạn có thể chỉ định URL trực tiếp và chúng tôi sẽ phân tích thành các trường cần thiết. Lưu ý rằng phương pháp này khó xử lý nhất đối với API của chúng tôi và cũng yêu cầu bạn chỉ định ngôn ngữ và vị trí chính xác trong URL. Trong hầu hết các trường hợp, chúng tôi không khuyến nghị dùng phương pháp này.
ví dụ:
https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS
Lưu ý: các tham số công cụ tìm kiếm sau không được hỗ trợ và sẽ tự động bị bỏ đặt nếu được chỉ định trong URL:lr,cr,as_qdr,as_sitesearch,as_occt,as_filetype.
- Kiểu: object | null · Response36Afe1097B20_SerpGoogleOrganicLiveRegularResponseInfo200
- Kiểu: number | null Định dạng: doublecost
tổng chi phí tác vụ, USD
- Kiểu: integer | nullstatus
_code mã trạng thái chung; bạn có thể tìm danh sách đầy đủ các mã phản hồi tại đây
- Kiểu: string | nullstatus
_message thông điệp thông tin chung; bạn có thể tìm danh sách đầy đủ các thông điệp thông tin chung tại đây
- Kiểu: array (object | null)[] | nulltasks
mảng tác vụ
- Kiểu: object | null · Response36Afe1097B20_SerpGoogleOrganicLiveRegularTaskInfo
- costKiểu: number | null Định dạng: double
tổng chi phí tác vụ, USD
- dataKiểu: object | null
chứa các tham số giống như bạn đã chỉ định trong yêu cầu POST
- propertyKiểu: object | null
Name
- idKiểu: string | null
mã định danh tác vụ; mã định danh tác vụ duy nhất trong hệ thống của chúng tôi ở định dạng UUID
- pathKiểu: array (string | null)[] | null
Đường dẫn URL
- resultKiểu: array (object | null)[] | null
mảng kết quả
- checkKiểu: string | null
_url URL trực tiếp đến kết quả công cụ tìm kiếm
bạn có thể dùng URL này để đảm bảo chúng tôi đã cung cấp kết quả chính xác - datetimeKiểu: string | null
ngày và giờ nhận được kết quả
theo định dạng UTC: “yyyy-mm-dd hh-mm-ss +00:00”
ví dụ:2019-11-15 12:57:46 +00:00 - itemKiểu: array (string | null)[] | null
_types các loại kết quả tìm kiếm được tìm thấy trong SERP
chứa các loại của tất cả kết quả tìm kiếm (items) được tìm thấy trong SERP trả về
các loại mục khả dụng:answer_box,app,carousel,multi_carousel,featured_snippet,google_flights,google_reviews,third_party_reviews,images,jobs,knowledge_graph,local_pack,hotels_pack,map,organic,paid,people_also_ask,related_searches,people_also_search,shopping,top_stories,twitter,video,events,recipes,top_sights,scholarly_articles,popular_products,questions_and_answers,find_results_on,stocks_box,commercial_units,local_services,google_hotels,math_solver,currency_box,product_considerations,short_videos,refine_products,perspectives,discussions_and_forums,compare_sites,ai_overviewlưu ý rằng mảng này chứa tất cả các loại kết quả tìm kiếm được tìm thấy trong SERP trả về;
tuy nhiên, endpoint này chỉ cung cấp dữ liệu chofeatured_snippet,organicvàpaid
để lấy tất cả các mục (bao gồm các tính năng SERP và đoạn trích phong phú) được tìm thấy trong SERP trả về, hãy tham khảo Google Organiс Advanced SERP endpoint - itemsKiểu: array (object | null)[] | null
các mục của phần tử
- pageKiểu: integer | null
số trang kết quả tìm kiếm
cho biết số trang SERP mà phần tử nằm trên đó - positionKiểu: string | null
căn lề của phần tử trong SERP
có thể nhận các giá trị sau:left,right - rectangleKiểu: object | null · Response36Afe1097B20_AiModeRectangleInfo
tham số hình chữ nhật
chứa tọa độ Descartes và kích thước pixel của đoạn trích kết quả trong SERP
bằngnullnếucalculate_rectanglestrong yêu cầu POST không được đặt thànhtrue- heightKiểu: number | null Định dạng: double
chiều cao của phần tử tính bằng pixel
- widthKiểu: number | null Định dạng: double
chiều rộng của phần tử tính bằng pixel
- xKiểu: number | null Định dạng: double
tọa độ trục x tọa độ trục x của góc trên bên trái đoạn trích kết quả, trong đó góc trên bên trái của màn hình là gốc tọa độ
- yKiểu: number | null Định dạng: double
tọa độ trục y tọa độ trục y của góc trên bên trái đoạn trích kết quả, trong đó góc trên bên trái của màn hình là gốc tọa độ
- typeKiểu: string | null
loại phần tử
- xpathKiểu: string | null
XPath của phần tử
- itemsKiểu: integer | null Định dạng: int64
_count số kết quả được trả về trong mảng
items - keywordKiểu: string | null
từ khóa nhận được trong mảng POST
từ khóa được trả về với %## đã giải mã (ký tự cộng '+' sẽ được giải mã thành dấu cách) - languageKiểu: string | null
_code mã ngôn ngữ trong mảng POST
- locationKiểu: integer | null
_code mã vị trí trong mảng POST
- pagesKiểu: integer | null Định dạng: int64
_count tổng số trang kết quả tìm kiếm đã truy xuất
tổng số SERP đã truy xuất trong kết quả - refinementKiểu: object | null · Response36Afe1097B20_RefinementChipsInfo
_chips chip tinh chỉnh tìm kiếm
- itemsKiểu: array (object | null)[] | null
các mục của phần tử
- domainKiểu: string | null
tên miền trong SERP
- optionsKiểu: array (object | null)[] | null
các tùy chọn tinh chỉnh tìm kiếm khác
- domainKiểu: string | null
tên miền trong SERP
- titleKiểu: string | null
tiêu đề của phần tử
- typeKiểu: string | null
loại phần tử
- urlKiểu: string | null
URL tìm kiếm với các tham số tinh chỉnh
- titleKiểu: string | null
tiêu đề của phần tử
- typeKiểu: string | null
loại phần tử
- urlKiểu: string | null
URL tìm kiếm với các tham số tinh chỉnh
- typeKiểu: string | null
loại phần tử
- xpathKiểu: string | null
XPath của phần tử
- seKiểu: string | null
_domain tên miền công cụ tìm kiếm trong mảng POST
- seKiểu: integer | null Định dạng: int64
_results _count tổng số kết quả trong SERP
- spellKiểu: object | null · Response36Afe1097B20_SpellInfo
tự động sửa lỗi của công cụ tìm kiếm
nếu công cụ tìm kiếm trả về kết quả cho một từ khóa đã được sửa, chúng tôi sẽ chỉ định từ khóa đã được công cụ tìm kiếm sửa và loại tự động sửa lỗi- keywordKiểu: string | null
từ khóa thu được nhờ tự động sửa lỗi của công cụ tìm kiếm kết quả sẽ được cung cấp cho từ khóa đã được sửa
- typeKiểu: string | null
loại tự động sửa lỗi giá trị khả dụng: did_you_mean, showing_results_for, no_results_found_for, including_results_for lưu ý: Yahoo và Yandex chỉ hỗ trợ loại tự động sửa lỗi sau: including_results_for
- typeKiểu: string | null
loại phần tử
- resultKiểu: integer | null Định dạng: int64
_count số phần tử trong mảng kết quả
- statusKiểu: integer | null
_code mã trạng thái của tác vụ do DataForSEO tạo; có thể nằm trong khoảng sau: 10000-60000; bạn có thể tìm danh sách đầy đủ các mã phản hồi tại đây
- statusKiểu: string | null
_message thông điệp thông tin của tác vụ; bạn có thể tìm danh sách đầy đủ các thông điệp thông tin chung tại đây
- timeKiểu: string | null
thời gian thực thi, giây
- Kiểu: integer | null Định dạng: int64tasks
_count số lượng tác vụ trong mảng tasks
- Kiểu: integer | null Định dạng: int64tasks
_error số lượng tác vụ trong mảng tasks được trả về kèm lỗi
- Kiểu: string | nulltime
tổng thời gian thực thi, giây
- Kiểu: string | nullversion
phiên bản hiện tại của API
application/json - 400
Không thể xử lý yêu cầu. Hãy kiểm tra các tham số yêu cầu.
- 401
Cần có khóa API Felo hợp lệ.
- 402
Không thể tiếp tục yêu cầu vì chưa đáp ứng yêu cầu thanh toán.
- 403
Tài khoản không được phép thực hiện thao tác này.
- 429
Đã đạt giới hạn yêu cầu hoặc giới hạn chi tiêu.
- 502
Dịch vụ không thể hoàn tất yêu cầu.
- 503
API hoặc dịch vụ thanh toán tạm thời không khả dụng.
- 504
Dịch vụ đã hết thời gian chờ khi xử lý yêu cầu.
- default
Phản hồi lỗi; phản hồi chuyển tiếp từ thượng nguồn có thể dùng định dạng của nhà cung cấp
application/json
curl https://openapi.felo.ai/v1/beta/dataforseo/serp/google/organic/live/regular \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '[
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]'
{
"version": null,
"status_code": null,
"status_message": null,
"time": null,
"cost": null,
"tasks_count": null,
"tasks_error": null,
"tasks": [
{
"id": null,
"status_code": null,
"status_message": null,
"time": null,
"cost": null,
"result_count": null,
"path": [
null
],
"data": null,
"result": [
{
"keyword": null,
"type": null,
"se_domain": null,
"location_code": null,
"language_code": null,
"check_url": null,
"datetime": null,
"spell": {
"keyword": null,
"type": null
},
"refinement_chips": {
"type": null,
"xpath": null,
"items": [
"[Max Depth Exceeded]"
]
},
"item_types": [
null
],
"se_results_count": null,
"pages_count": null,
"items_count": null,
"items": [
{
"type": null,
"page": null,
"position": null,
"xpath": null,
"rectangle": "[Max Depth Exceeded]"
}
]
}
]
}
]
}