Trả lời nhanh
Endpoint tìm kiếm của SerpCrypto nhận những tham số nào?
GET https://serpcrypto.com/api/v1/search nhận một tham số bắt buộc, q, và chín tham số tùy chọn: engine, gl, hl, location, google_domain, device, page, safe và period. SerpCrypto trả về JSON và tính 1 credit mỗi lần tìm kiếm thành công trên tất cả 6 engine; lỗi thì miễn phí. Các pack bắt đầu từ 7,50 US$ cho 10.000 tìm kiếm, thanh toán bằng crypto, không cần KYC.
Tôi xác thực thế nào?
Gửi khóa của bạn theo một trong hai cách. Cách khuyến nghị là header Authorization: Bearer YOUR_KEY. Cách còn lại là query parameter api_key=YOUR_KEY, tiện cho một lần thử nhanh trên tab trình duyệt.
Khóa bị thiếu, sai hoặc đã thu hồi sẽ nhận 401 invalid_api_key và không tốn gì. Khóa API bạn có thể tạo và thu hồi bất cứ lúc nào từ dashboard, để bạn có thể cấp cho mỗi script hay mỗi server một khóa riêng và thu hồi một khóa mà không ảnh hưởng đến các khóa khác.
Chạy một tìm kiếm
GET/api/v1/search
Chạy một tìm kiếm trên engine đã chọn và trả về trang kết quả dưới dạng JSON. Một lần tìm kiếm thành công dùng 1 credit, bất kể engine nào; một lỗi không dùng credit nào. Tham số nằm trong query string, được URL-encode. Ví dụ hỏi Google về các nhà rang cà phê ở Austin, Texas; các ID, số đếm và kết quả chỉ để minh họa.
Xác thực: khóa API trong header Authorization: Bearer API_KEY.
Tham số
| Tên | Vị trí | Loại | Bắt buộc | Mô tả |
|---|---|---|---|---|
q | query | string | Có | Truy vấn tìm kiếm, đúng như người dùng gõ. Các toán tử tìm kiếm như dấu ngoặc kép hoặc site: là một phần của truy vấn. |
engine | query | string | Không | google (mặc định), google_news, google_images, google_maps, google_shopping hoặc bing. |
gl | query | string | Không | Quốc gia của kết quả: mã ISO 3166-1 alpha-2 viết thường, ví dụ us, de hoặc br. Mặc định us. |
hl | query | string | Không | Ngôn ngữ giao diện, ví dụ en, de hoặc pt-BR. Mặc định en. |
location | query | string | Không | Địa điểm cấp thành phố, viết dạng City, Region, Country, ví dụ Austin, Texas, United States. Xem địa điểm. |
google_domain | query | string | Không | Tên miền Google để tìm kiếm, ví dụ google.de. Mặc định: tên miền của quốc gia gl. Bị bỏ qua khi engine=bing. |
device | query | string | Không | desktop (mặc định) hoặc mobile. |
page | query | integer | Không | Trang kết quả từ 1 (mặc định) đến 10. Mỗi trang là một lần tìm kiếm riêng và dùng 1 credit. |
safe | query | string | Không | active lọc kết quả người lớn; off (mặc định) thì không. |
period | query | string | Không | Chỉ lấy kết quả trong giờ qua (h), ngày qua (d), tuần qua (w), tháng qua (m) hoặc năm qua (y). |
api_key | query | string | Không | Khóa của bạn, nếu bạn không gửi header Authorization. |
Phản hồi 200
{
"search_metadata": {
"id": "srch_7f3a9c2e41b8",
"status": "success",
"engine": "google",
"created_at": "2026-10-22T09:14:05Z",
"credits_used": 1
},
"search_parameters": {
"engine": "google",
"q": "coffee roasters",
"gl": "us",
"hl": "en",
"location": "Austin, Texas, United States",
"google_domain": "google.com",
"device": "desktop",
"page": 1
},
"search_information": {
"total_results": 18600000,
"query_displayed": "coffee roasters"
},
"local_results": [
{
"position": 1,
"title": "Example Coffee Roasters",
"address": "123 Example St, Austin, TX",
"rating": 4.7,
"reviews": 312,
"type": "Coffee roasters"
}
],
"organic_results": [
{
"position": 1,
"title": "The 12 best coffee roasters in Austin",
"link": "https://www.example.com/austin/coffee-roasters",
"displayed_link": "www.example.com › austin › coffee",
"snippet": "From light Nordic roasts to dark espresso blends, these local roasters…",
"date": "Sep 30, 2026"
},
{
"position": 2,
"title": "Example Roasting Co. | Fresh beans, roasted in Austin",
"link": "https://www.example.org/",
"displayed_link": "www.example.org",
"snippet": "Small-batch coffee roasted every weekday and shipped the same day…"
}
],
"people_also_ask": [
{
"question": "What is the oldest coffee roaster in Austin?",
"snippet": "…",
"title": "Austin coffee history",
"link": "https://www.example.net/austin-coffee-history"
}
],
"related_searches": [
{
"query": "coffee roasters near me"
},
{
"query": "coffee roasters austin wholesale"
}
],
"pagination": {
"current": 1,
"next_page": 2
}
}Ví dụ mã
curl -sG "https://serpcrypto.com/api/v1/search" \
-H "Authorization: Bearer $SERPCRYPTO_API_KEY" \
--data-urlencode "q=coffee roasters" \
--data-urlencode "location=Austin, Texas, United States" \
-d gl=us -d hl=en -d device=desktopimport os
import requests
r = requests.get(
"https://serpcrypto.com/api/v1/search",
params={
"q": "coffee roasters",
"location": "Austin, Texas, United States",
"gl": "us",
"hl": "en",
},
headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]},
timeout=60,
)
r.raise_for_status()
print(r.json()["organic_results"][0]["link"])const params = new URLSearchParams({
q: "coffee roasters",
location: "Austin, Texas, United States",
gl: "us",
hl: "en",
});
const res = await fetch("https://serpcrypto.com/api/v1/search?" + params, {
headers: { Authorization: "Bearer " + process.env.SERPCRYPTO_API_KEY },
});
const data = await res.json();
console.log(data.organic_results?.[0]?.link);Có những giá trị engine nào và mỗi giá trị trả về gì?
Cấu trúc (search_metadata, search_parameters, search_information) giống nhau trên mọi engine. Một block chỉ xuất hiện khi trang hiển thị nó.
engine | Nguồn | Các block chính trong câu trả lời |
|---|---|---|
google | Google Search | ai_overview, organic_results, ads, people_also_ask, local_results, knowledge_graph, top_stories, inline_videos, shopping_results, related_searches, pagination |
google_news | Google News | news_results: tiêu đề, liên kết, nguồn, ngày, đoạn trích, ảnh thu nhỏ |
google_images | Google Images | images_results: URL gốc và kích thước, ảnh thu nhỏ, trang nguồn |
google_maps | Google Maps | local_results: tên, địa chỉ, điện thoại, website, đánh giá, số nhận xét, danh mục, giờ mở cửa, tọa độ |
google_shopping | Google Shopping | shopping_results: tiêu đề, giá, giá trích xuất, tiền tệ, người bán, giao hàng, đánh giá |
bing | Bing | organic_results, related_searches |
Đọc số dư credit của bạn
GET/api/v1/credits
Trả về số credit còn lại trên tài khoản của bạn, số credit đã dùng từ 00:00 UTC và số lượt tìm kiếm tài khoản của bạn có thể chạy cùng lúc. Lệnh gọi này miễn phí. Các giá trị bên dưới chỉ là ví dụ.
Xác thực: khóa API trong header Authorization: Bearer API_KEY.
Phản hồi 200
{
"credits_remaining": 84210,
"credits_used_today": 1290,
"concurrency_limit": 10
}Ví dụ mã
curl -s "https://serpcrypto.com/api/v1/credits" \
-H "Authorization: Bearer $SERPCRYPTO_API_KEY"import os
import requests
r = requests.get(
"https://serpcrypto.com/api/v1/credits",
headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]},
timeout=30,
)
r.raise_for_status()
print(r.json()["credits_remaining"])const res = await fetch("https://serpcrypto.com/api/v1/credits", {
headers: { Authorization: "Bearer " + process.env.SERPCRYPTO_API_KEY },
});
const { credits_remaining } = await res.json();
console.log(credits_remaining);API có thể trả về những lỗi nào?
Mọi lỗi đều có body {"error": {"code": "…", "message": "…"}}. Trang lỗi giải thích từng lỗi và hiển thị mã thử lại.
| HTTP | code | Khi nào xảy ra | Có tính phí |
|---|---|---|---|
| 400 | invalid_parameter | Thiếu tham số bắt buộc hoặc giá trị nằm ngoài danh sách cho phép | Không |
| 401 | invalid_api_key | Thiếu khóa, sai khóa hoặc khóa đã bị thu hồi | Không |
| 402 | insufficient_credits | Tài khoản của bạn không còn credit | Không |
| 429 | concurrency_limit | Quá nhiều lượt tìm kiếm đang chạy cùng lúc trên tài khoản của bạn | Không |
| 502 | search_failed | Engine hoặc bộ thu thập gặp lỗi với truy vấn này; hãy thử lại | Không |
| 504 | search_timeout | Không có phản hồi kịp thời; hãy thử lại | Không |
Chính xác thì khoản nào bị tính phí?
- Một lần tìm kiếm thành công = một credit, trên mọi engine, kể cả Google Maps và Google Shopping.
- Mỗi trang kết quả là một lần tìm kiếm. Khoảng 10 kết quả organic mỗi trang, đúng như Google đã trả về kể từ khi ngừng áp dụng num=100 vào tháng 9 năm 2025; mỗi trang thêm là thêm một credit.
- Lỗi không mất phí: mọi câu trả lời có HTTP status khác 200 đều không dùng credit.
- Đọc số dư credit miễn phí.
Credit tìm kiếm trả trước không bao giờ hết hạn: các lượt tìm kiếm chưa dùng vẫn nằm trong tài khoản của bạn cho đến khi bạn dùng. Các pack có giá từ 7,50 US$ cho 10.000 tìm kiếm đến 0,30 US$/1K lượt tìm kiếm ở pack lớn nhất; xem bảng giá.
Tôi nên mã hóa truy vấn như thế nào?
Gửi q dưới dạng URL-encoded, như mọi giá trị query-string: dấu cách thành %20 hoặc +, và các chữ có dấu được mã hóa theo UTF-8. curl làm việc này với --data-urlencode, Python requests và httpx làm với params=, còn Node.js làm với URLSearchParams.
Viết truy vấn đúng như một người sẽ gõ vào ô tìm kiếm. Dấu ngoặc kép, dấu trừ hay site: vẫn nằm trong q; engine tự quyết định cách áp dụng chúng, giống như với một người truy cập.
API có được đánh phiên bản không?
Có. Phiên bản nằm trong path: /api/v1/. Các field hoặc block mới có thể xuất hiện trong câu trả lời của phiên bản 1, nên code của bạn nên bỏ qua những key mà nó không biết. Việc xóa hoặc đổi tên một field sẽ đi kèm một phiên bản mới trong path, chứ không phải là thay đổi trên v1.
Câu hỏi về tài liệu tham khảo API
Tôi có thể gửi yêu cầu POST với JSON body không?
Không có trong phiên bản 1: cả hai endpoint đều nhận yêu cầu GET với các tham số trong query string. Điều này giúp mọi lệnh gọi dễ tái tạo bằng curl hoặc trình duyệt, và dễ ghi log mà không cần body.
Một lần tìm kiếm trả về bao nhiêu kết quả?
Khoảng 10 kết quả organic mỗi trang, đúng như Google đã trả về kể từ khi ngừng áp dụng num=100 vào tháng 9 năm 2025; mỗi trang thêm là thêm một credit. Để thu thập 30 kết quả, hãy gửi yêu cầu page=1, page=2 và page=3: ba lần tìm kiếm, ba credit.
Điều gì xảy ra khi credit của tôi hết?
Lần tìm kiếm tiếp theo trả về 402 insufficient_credits và không dùng credit nào. Mua thêm một pack từ số dư của bạn trên trang giá; khóa của bạn vẫn hoạt động và các lần tìm kiếm tiếp tục ngay lập tức.
Tôi có thể dùng cùng một khóa từ nhiều server không?
Có. Khóa không gắn với địa chỉ IP. Thứ bị giới hạn là số lần tìm kiếm chạy đồng thời trên tài khoản: concurrency_limit trong GET /credits sẽ cho ra con số đó.