CarianGoogle API5 credits

search_web

Indeks Google, sebagai JSON. Setiap hasil membawa tajuk, URL, cebisan dan varian bersorot milik Google sendiri, di samping blok metadata dengan jumlah padanan dan tempoh carian itu. Penapis untuk tapak, jenis fail, bahasa, kebaruan dan carian selamat digunakan sebagai operator Google yang sebenar.

Kes Penggunaan

Saluran Penyelidikan

Cari sumber bagi sesuatu topik, kemudian suapkan URL itu terus ke batch_scrape atau extract_content.

Carian Terhad kepada Tapak

Tetapkan site untuk mencari dalam satu domain — pengganti kotak carian tapak yang tidak wujud atau berfungsi dengan buruk.

Pemburuan Dokumen

Gabungkan file_type dengan pertanyaan untuk mencari PDF, hamparan atau dek slaid tentang sesuatu subjek.

Pemantauan Kebaruan

Hadkan kepada hari atau minggu lepas dengan time_range untuk menangkap liputan baharu tentang sesuatu topik atau jenama.

Penemuan Persaingan

Lihat halaman yang ditonjolkan Google bagi istilah yang anda pentingkan, dan berapa banyak hasil yang wujud secara keseluruhan.

Pengukuhan Ejen

Berikan model hasil carian semasa untuk digunakan, dan bukannya bergantung pada apa yang dihafalnya.

Endpoint

POST/api/v1/tools/search_web

Auth Required

1 req/s pada pelan Free

5 credits

Parameters

limit menerima sehingga 100, tetapi Google mengembalikan paling banyak 10 hasil setiap permintaan — limit yang lebih besar tidak gagal, ia hanya memberi anda 10. Halusuri selebihnya dengan offset, satu carian (dan 5 credits) setiap halaman. Hantar tepat satu daripada query atau queries: kelompok queries menjalankan satu carian Google bagi setiap pertanyaan, dan 5 credits × bilangan pertanyaan yang anda hantar — 50 bagi maksimum 10 — ialah unjuran, satu siling dan bukan cajnya. Hanya pertanyaan yang mengembalikan hasil yang dicaj.

Name	Type	Required	Default	Description
query	string	Optional	-	Istilah carian. Operator Google yang anda taip di sini berfungsi seperti dalam kotak carian, dan `site` serta `file_type` ditambah sebagai operator di atasnya. Hantar tepat satu daripada `query` atau `queries`. Example: mcp server for web scraping
queries	string[]	Optional	-	Antara 1 hingga 10 pertanyaan carian untuk dijalankan dalam satu panggilan, sebagai ganti `query`. Setiap satu menjalani saluran yang sama seperti carian tunggal, dan muatannya kembali dalam `results_by_query` — satu senarai mengikut susunan anda menghantarnya, satu entri bagi setiap pertanyaan yang membawa `query` miliknya sendiri berserta medan carian itu, atau `query` dan `error` apabila carian itu gagal. `queries` mengembalikan input anda sebagaimana adanya dan `count` ialah panjangnya. Satu panggilan `search_web` berharga 5 credits bagi setiap pertanyaan yang mengembalikan hasil — satu `query` tunggal berharga 5, dan kelompok `queries` diunjurkan pada 5 × bilangan pertanyaan yang dihantar, iaitu satu siling: setiap pertanyaan yang gagal tidak dicaj, jadi kelompok yang tiada satu pun berjaya tidak berharga apa-apa. Pertanyaan yang diulang dalam senarai itu berjalan dua kali dan dicaj dua kali apabila kedua-dua larian mengembalikan hasil. Kelompok yang tiada satu pun berjaya tetap 200 yang membawa sampul biasa: `count` sebagaimana dihantar, satu entri `{ query, error }` bagi setiap pertanyaan, dan `credits_used: 0`. Hantar tepat satu daripada `query` atau `queries` — kedua-duanya, atau tiada satu pun, ialah 400. Example: ["mcp server for web scraping", "model context protocol tools"]
limit	number	Optional	10	Hasil untuk dikembalikan, 1-100 — tetapi Google mengehadkan satu permintaan kepada 10, jadi apa-apa melebihi 10 berkelakuan sebagai 10. Example: 10
offset	number	Optional	0	Indeks berasaskan sifar bagi hasil pertama. Gunakan 10, 20, 30 untuk berhalaman. Setiap halaman ialah carian berasingan dan berharga 5 credits. Example: 10
lang	string	Optional	-	Hadkan kepada dokumen dalam satu bahasa, sebagai kod ISO 639-1. Dikembalikan dalam `search_metadata.lang`, yang lalai kepada `en` apabila anda meninggalkannya. Example: es
site	string	Optional	-	Hadkan kepada satu domain. Ditambah pada pertanyaan anda sebagai `site:<domain>`, jadi ia berkelakuan sama seperti menaipnya. Example: docs.anthropic.com
safe_search	boolean	Optional	-	Hidupkan penapisan SafeSearch Google. Dimatikan melainkan anda menetapkannya. Example: true
time_range	string	Optional	-	Hadkan mengikut kebaruan: `day`, `week`, `month`, `year` atau `all`. `all` tidak mengenakan sekatan, dan ia juga nilai lalai. Example: week
file_type	string	Optional	-	Hadkan kepada satu sambungan fail. Ditambah sebagai `filetype:<ext>`, jadi `pdf`, `xlsx` dan `pptx` semuanya berfungsi. Example: pdf
redact_pii	boolean \| object	Optional	false	Buang data peribadi daripada teks yang dikembalikan oleh panggilan ini, sebelum hasilnya disimpan atau dihantar balik. Terpakai pada tajuk, cebisan dan carian berkaitan yang dikembalikan Google; `query` yang anda hantar dikembalikan sebagaimana adanya. `true` ialah singkatan bagi `{ mode: "fast" }` — keempat-empat kelas regex, bertag. Setiap kali anda meminta penyuntingan, respons membawa `redaction: { entities, count, mode }` di dalam `data`, walaupun tiada apa-apa yang sepadan (`count: 0`), jadi "tiada apa-apa ditemui" tidak pernah disalah anggap sebagai "parameter itu diabaikan"; kelas tanpa padanan ditinggalkan dan bukan dilaporkan sebagai `0`. Penyuntingan berjalan sebelum hasil itu disimpan, jadi hasil besar yang dibaca kemudian dengan [read_result](/docs/api-reference/tools/read-result) sudah pun disunting. Dua batas yang disengajakan: alamat (`url`, `link`, `href`, `canonical_url`) tidak pernah disunting, dan kiraan yang diperoleh daripada teks (`content_length`, `word_count`, `character_count`) menggambarkan teks itu sebagaimana ia diekstrak, sebelum penyuntingan. Example: true
max_inline_chars	number	Optional	40000	Hasil terbesar yang dikembalikan sebaris, dalam aksara JSON-nya (1,000-10,000,000). Melebihinya, respons membawa `preview` (`max_inline_chars` aksara pertama JSON yang diformat), `result_handle`, `total_chars`, `truncated: true` dan `expires_at`, dan [read_result](/docs/api-reference/tools/read-result) membaca selebihnya dengan 1 credit setiap panggilan. Hasil tersimpan disimpan selama 1 jam. Example: 40000

Carian Berkelompok

Hantar queries dan bukan query untuk menjalankan sehingga 10 carian dalam satu panggilan. Setiap pertanyaan ialah carian Google tunggal yang sama seperti panggilan query — API ini tidak mengembangkan pertanyaan, tidak menggunakan cache, tidak menyahduakan dan tidak menyusun semula keputusan — dan setiap pertanyaan yang mengembalikan keputusan dicaj 5 credits.

terminalBash

curl -X POST https://crawlforge.dev/api/v1/tools/search_web \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      "mcp server for web scraping",
      "model context protocol tools"
    ],
    "limit": 10,
    "redact_pii": true
  }'

Respons Berkelompok

results_by_query ialah satu senarai mengikut susunan anda menghantar pertanyaan itu, satu entri bagi setiap pertanyaan, jadi pertanyaan yang diulang muncul dua kali. Pertanyaan yang gagal membawa error menggantikan hasilnya dan tidak dicaj; panggilan itu mengembalikan 200 dalam kedua-dua keadaan, termasuk apabila setiap pertanyaan gagal, jadi credits_used ialah bilangan yang benar-benar berjaya didarab 5. Panggilan query tunggal tidak berubah: queries, count dan results_by_query tidak muncul padanya.

response.jsonJson

{
  "success": true,
  "data": {
    "queries": ["mcp server for web scraping", "model context protocol tools"],
    "count": 2,
    "results_by_query": [
      {
        "query": "mcp server for web scraping",
        "search_metadata": { "total_results": 48200, "results_returned": 10 },
        "results": [
          {
            "title": "CrawlForge MCP Server",
            "url": "https://www.crawlforge.dev/",
            "snippet": "Write to <EMAIL> for access."
          }
        ]
      },
      {
        "query": "model context protocol tools",
        "error": "Search failed: Google API daily quota exceeded"
      }
    ],
    "redaction": { "entities": { "EMAIL": 1 }, "count": 1, "mode": "fast" }
  },
  "credits_used": 5,
  "credits_remaining": 995,
  "processing_time": 720
}

Contoh Permintaan

terminalBash

curl -X POST https://crawlforge.dev/api/v1/tools/search_web \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mcp server for web scraping",
    "limit": 10,
    "time_range": "month",
    "safe_search": true
  }'

Contoh Respons

200 OK460ms

{
  "success": true,
  "data": {
    "query": "mcp server for web scraping",
    "search_metadata": {
      "total_results": 48200,
      "results_returned": 1,
      "offset": 0,
      "search_time": 0.312,
      "lang": "en",
      "safe_search": false,
      "time_range": "month",
      "site": null,
      "file_type": null
    },
    "results": [
      {
        "title": "CrawlForge MCP Server — 31 web tools for Claude",
        "url": "https://www.crawlforge.dev/",
        "snippet": "Search, scrape, crawl and extract from any site through one MCP server.",
        "displayLink": "www.crawlforge.dev",
        "formattedUrl": "https://www.crawlforge.dev/",
        "htmlSnippet": "Search, scrape, crawl and extract from any site through one MCP server.",
        "htmlTitle": "CrawlForge MCP Server — 31 web tools for Claude",
        "cacheId": "x8Kd0PqR2mUJ",
        "pagemap": {
          "metatags": [
            {
              "og:type": "website"
            }
          ]
        }
      }
    ],
    "spelling_correction": "mcp server for web scraping",
    "related_searches": [
      "mcp web scraping tools",
      "model context protocol scraper"
    ]
  },
  "credits_used": 5,
  "credits_remaining": 995,
  "processing_time": 460
}

Field Descriptions

data.queryIstilah yang benar-benar dicari oleh Google, yang boleh berbeza daripada apa yang anda hantar

data.search_metadata.total_resultsAnggaran Google bagi dokumen yang sepadan. Satu anggaran, bukan kiraan yang boleh anda halusuri

data.search_metadata.results_returnedPanjang `results` — paling banyak 10

data.search_metadata.search_timeSaat yang digunakan Google, seperti yang dilaporkan oleh Google. Bukan kependaman permintaan anda

data.results[].urlPautan destinasi. `formattedUrl` ialah versi paparan Google bagi alamat yang sama

data.results[].htmlSnippetCebisan dengan penyorotan istilah `<b>` Google dikekalkan. Lepaskannya sebelum memaparkan

data.results[].cacheIdPengecam cache Google, apabila ia ada. Tiada bagi hasil yang tidak dicache oleh Google

data.results[].pagemapData berstruktur yang diangkat Google daripada halaman — tag meta, imej, jenis schema.org. Bentuknya berbeza bagi setiap hasil dan boleh jadi tiada

data.spelling_correctionEjaan yang dicadangkan Google, atau `null` apabila tiada

data.related_searchesCadangan pertanyaan berkaitan. Kerap kali merupakan tatasusunan kosong

credits_used5 credits tetap setiap carian, apa jua `limit` yang anda minta

Pengendalian Ralat

Pertanyaan Tidak Sah (400 Bad Request)

VALIDATION_ERROR. query diperlukan dan tidak boleh kosong. Status yang sama meliputi limit di luar 1-100, offset negatif, atau time_range yang bukan salah satu daripada lima nilai yang diterima. Menghantar kedua-dua query dan queries, atau tiada satu pun, ialah 400 yang sama, begitu juga tatasusunan queries yang kosong atau melebihi 10 entri, objek redact_pii yang menamakan entiti yang tidak boleh disunting oleh API ini, atau redact_pii dengan mode: "model" — yang memerlukan LLM yang tidak dijalankan oleh API ini.

Carian Gagal (500 Internal Server Error)

TOOL_ERROR. Merangkumi ralat Google di hulu, kuota harian yang habis, dan tamat masa selepas 10 saat. Mesejnya menyatakan puncanya. Carian yang gagal tidak dicaj. Inilah laluan query tunggal: satu carian yang gagal memberi ralat seperti biasa. Kelompok queries tidak pernah sampai ke sini — pertanyaan yang gagal dilaporkan dalam entri results_by_query miliknya sendiri dan panggilan itu tetap mengembalikan 200, walaupun setiap pertanyaan gagal.

Nota:

Carian yang tidak sepadan dengan apa-apa mengembalikan 200 dengan tatasusunan results yang kosong dan total_results: 0 — bukan ralat. Periksa results_returned dan bukannya bergantung pada kod status.

Kos Credit

5 credits

5 credits setiap carian

Satu carian ialah satu caj, sama ada ia mengembalikan 10 hasil atau tiada. Berhalaman dengan offset bermakna satu lagi carian, jadi sepuluh halaman berharga 50 credits. Carian yang gagal tidak dicaj. Satu panggilan search_web berharga 5 credits bagi setiap pertanyaan yang mengembalikan hasil — satu query tunggal berharga 5, dan kelompok queries diunjurkan pada 5 × bilangan pertanyaan yang dihantar, iaitu satu siling: setiap pertanyaan yang gagal tidak dicaj, jadi kelompok yang tiada satu pun berjaya tidak berharga apa-apa. Sepuluh pertanyaan dalam satu panggilan diunjurkan pada 50 dan berharga 50 hanya jika kesepuluh-sepuluhnya mengembalikan hasil. redact_pii dalam mod fast lalainya tidak menambah apa-apa.

Apa yang Disertakan:

Indeks langsung Google, bukan salinan cache

Tajuk, URL, cebisan dan varian bersorot Google

Anggaran jumlah padanan dan masa carian

Penapis site, file_type, lang, time_range dan carian selamat

Pembetulan ejaan dan carian berkaitan apabila Google membekalkannya

Cadangan Pelan:

Free Plan: 1,000 credits percubaan sekali sahaja = 200 carian

Hobby Plan: 5,000 credits = 1,000 carian ($19/mo)

Professional Plan: 100,000 credits = 20,000 carian ($99/mo)