DataForSEO
SEO, search-engine results, keyword research, backlinks and AI visibility data.
Tạo tác vụ SERP organic Google
Xếp hàng kết quả xếp hạng cho một từ khóa trên Google, trả về id tác vụ trong tasks[0].id. Đượ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. Bản trực tiếp trả lời ngay và đơn giản hơn cho một truy vấn đơn lẻ; hãy xếp hàng khi lô yêu cầu sẽ kéo dài hơn một lượt gọi công cụ.
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.02.
- 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)[]
- browserKiểu: integer | null
_screen _height chiều cao màn hình trình duyệt
trường tùy chọn
bạn có thể đặt chiều cao màn hình trình duyệt tùy chỉnh để tính xếp hạng pixel cho một thiết bị cụ thể;
có thể chỉ định trong khoảng sau:
240-9999;theo mặc định, tham số được đặt thành:
1080chodesktop;640chomobiletrênandroid;812chomobiletrêniOS;Lưu ý: để dùng tham số này, hãy đặt
calculate_rectanglesthànhtrue - browserKiểu: integer | null
_screen _resolution _ratio tỷ lệ phân giải màn hình trình duyệt
trường tùy chọn
bạn có thể đặt tỷ lệ phân giải màn hình trình duyệt tùy chỉnh để tính xếp hạng pixel cho một thiết bị cụ thể;
có thể chỉ định trong khoảng sau:
0.5-3;theo mặc định, tham số được đặt thành:
1chodesktop;3chomobiletrênandroid;3chomobiletrêniOS;Lưu ý: để dùng tham số này, hãy đặt
calculate_rectanglesthànhtrue - browserKiểu: integer | null Định dạng: int64
_screen _width chiều rộng màn hình trình duyệt
trường tùy chọn
bạn có thể đặt chiều rộng màn hình trình duyệt tùy chỉnh để tính xếp hạng pixel cho một thiết bị cụ thể;
có thể chỉ định trong khoảng sau:
240-9999;theo mặc định, tham số được đặt thành:
1920chodesktop;360chomobiletrênandroid;375chomobiletrêniOS;Lưu ý: để dùng tham số này, hãy đặt
calculate_rectanglesthànhtrue - calculateKiểu: boolean | null
_rectangles tính xếp hạng pixel cho các phần tử SERP trong kết quả nâng cao
trường tùy chọn
xếp hạng pixel là khoảng cách giữa đoạn trích kết quả và góc trên bên trái màn hình;
Truy cập Trung tâm trợ giúp để tìm hiểu thêm>>
theo mặc định, tham số được đặt thành
falseLưu ý: bạn sẽ bị tính thêm $0.0006 khi dùng tham số này
- 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:
700
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 - expandKiểu: boolean | null
_ai _overview mở rộng tổng quan AI
trường tùy chọn
đặt thành
trueđể mở rộng mụcai_overview;giá trị mặc định:
false;Lưu ý: tham số này chỉ áp dụng cho kết quả tác vụ HTML
- 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
tìm hiểu thêm về quy tắc và giới hạn của các trường
keywordvàkeywordstrong API DataForSEO tại bài viết Trung tâm trợ giúp này - 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 - loadKiểu: boolean | null
_async _ai _overview tải tổng quan AI không đồng bộ
trường tùy chọn
đặt thành
trueđể nhận các mụcai_overviewtrong SERP ngay cả khi chúng được tải bất đồng bộ;nếu đặt thành
false, bạn chỉ nhận được các mụcai_overviewtừ bộ nhớ đệm;giá trị mặc định:
falseLưu ý: bạn sẽ bị tính thêm $0.0006 khi dùng tham số này;
nếu phần tử không có hoặc chứa
"asynchronous_ai_overview": false, toàn bộ phí bổ sung sẽ được hoàn lại vào số dư tài khoản của bạn - 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 - peopleKiểu: integer | null
_also _ask _click _depth số lần nhấp vào phần tử tương ứng
trường tùy chọn
chỉ định độ sâu nhấp trên phần tử
people_also_askđể nhận thêm các mụcpeople_also_ask_element;Lưu ý tài khoản của bạn sẽ bị tính thêm $0.00015 cho mỗi lần nhấp bất kể độ ưu tiên tác vụ;
nếu phần tử không có hoặc chúng tôi thực hiện ít lần nhấp hơn số bạn chỉ định, toàn bộ phí bổ sung sẽ được hoàn lại vào số dư tài khoản của bạn
giá trị khả dụng: từ
1đến4 - pingbackKiểu: string | null
_url URL thông báo của tác vụ đã hoàn tất
trường tùy chọn
khi tác vụ hoàn tất, chúng tôi sẽ thông báo cho bạn bằng yêu cầu GET gửi đến URL bạn đã chỉ định
bạn có thể dùng chuỗi ‘$id’ làm biến
$idvà ‘$tag’ làm biến$tagđược mã hóa URL. Chúng tôi sẽ đặt các giá trị cần thiết trước khi gửi yêu cầu.ví dụ:
http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagLưu ý: ký tự đặc biệt trong
pingback_urlsẽ được mã hóa URL;cụ thể, ký tự
#sẽ được mã hóa thành%23
tìm hiểu thêm trên Trung tâm trợ giúp của chúng tôi
- postbackKiểu: string
_data kiểu dữ liệu postback_url
trường bắt buộc nếu bạn chỉ định
postback_urltương ứng với kiểu dữ liệu sẽ được gửi đến máy chủ của bạn
giá trị khả dụng:
regular,advanced,html - postbackKiểu: string | null
_url URL để gửi kết quả tác vụ
trường tùy chọn
khi tác vụ hoàn tất, chúng tôi sẽ gửi yêu cầu POST với kết quả được nén ở định dạng
gzipđếnpostback_urlbạn đã chỉ địnhbạn có thể dùng chuỗi ‘$id’ làm biến
$idvà ‘$tag’ làm biến$tagđược mã hóa URL. Chúng tôi sẽ đặt các giá trị cần thiết trước khi gửi yêu cầuví dụ:
http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagLưu ý: các ký tự đặc biệt trong
postback_urlsẽ được mã hóa URL;tức là, ký tự
#sẽ được mã hóa thành%23
tìm hiểu thêm trên Trung tâm trợ giúp của chúng tôi
- priorityKiểu: integer | null
độ ưu tiên tác vụ
trường tùy chọn
có thể nhận các giá trị sau:
1 – độ ưu tiên thực thi bình thường (đặt mặc định);
2 – độ ưu tiên thực thi cao
Bạn sẽ bị tính thêm phí cho các tác vụ có độ ưu tiên thực thi cao.Chi phí có thể được tính trên trang Bảng giá.
- removeKiểu: array string[] | null
_from _url xóa các tham số cụ thể khỏi URL
trường tùy chọn
bạn có thể dùng trường này để chỉ định tối đa 10 tham số cần xóa khỏi URL trong kết quả
ví dụ:
"remove_from_url": ["srsltid"] - 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
xem danh sách 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
_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_SerpGoogleOrganicTaskPostResponseInfo200
- 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_SerpGoogleOrganicTaskPostTaskInfo
- 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: object | null
mảng kết quả
trong trường hợp này, giá trị sẽ lànull - 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/task_post \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '[
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
},
{
"language_name": "English",
"location_name": "United States",
"keyword": "albert einstein",
"priority": 2,
"tag": "some_string_123",
"pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
},
{
"url": "https://www.google.co.uk/search?q=albert%20einstein&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
"postback_data": "html",
"postback_url": "https://your-server.com/postbackscript"
}
]'
{
"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": null
}
]
}