Pesquisa - Firecrawl Docs

Pesquise e, opcionalmente, faça scraping dos resultados de busca

curl --request POST \
  --url https://api.firecrawl.dev/v2/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "categories": [
    {
      "type": "github"
    }
  ],
  "country": "US",
  "enterprise": [],
  "excludeDomains": [
    "<string>"
  ],
  "ignoreInvalidURLs": false,
  "includeDomains": [
    "<string>"
  ],
  "limit": 10,
  "location": "<string>",
  "scrapeOptions": {},
  "sources": [
    "web"
  ],
  "tbs": "<string>",
  "threatProtection": {
    "blacklist": [
      "<string>"
    ],
    "blockedTlds": [
      "<string>"
    ],
    "riskScoreThreshold": 75,
    "whitelist": [
      "<string>"
    ]
  },
  "timeout": 60000
}
'

import requests

url = "https://api.firecrawl.dev/v2/search"

payload = {
    "query": "<string>",
    "categories": [{ "type": "github" }],
    "country": "US",
    "enterprise": [],
    "excludeDomains": ["<string>"],
    "ignoreInvalidURLs": False,
    "includeDomains": ["<string>"],
    "limit": 10,
    "location": "<string>",
    "scrapeOptions": {},
    "sources": ["web"],
    "tbs": "<string>",
    "threatProtection": {
        "blacklist": ["<string>"],
        "blockedTlds": ["<string>"],
        "riskScoreThreshold": 75,
        "whitelist": ["<string>"]
    },
    "timeout": 60000
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    query: '<string>',
    categories: [{type: 'github'}],
    country: 'US',
    enterprise: [],
    excludeDomains: ['<string>'],
    ignoreInvalidURLs: false,
    includeDomains: ['<string>'],
    limit: 10,
    location: '<string>',
    scrapeOptions: {},
    sources: ['web'],
    tbs: '<string>',
    threatProtection: {
      blacklist: ['<string>'],
      blockedTlds: ['<string>'],
      riskScoreThreshold: 75,
      whitelist: ['<string>']
    },
    timeout: 60000
  })
};

fetch('https://api.firecrawl.dev/v2/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firecrawl.dev/v2/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'query' => '<string>',
    'categories' => [
        [
                'type' => 'github'
        ]
    ],
    'country' => 'US',
    'enterprise' => [
        
    ],
    'excludeDomains' => [
        '<string>'
    ],
    'ignoreInvalidURLs' => false,
    'includeDomains' => [
        '<string>'
    ],
    'limit' => 10,
    'location' => '<string>',
    'scrapeOptions' => [
        
    ],
    'sources' => [
        'web'
    ],
    'tbs' => '<string>',
    'threatProtection' => [
        'blacklist' => [
                '<string>'
        ],
        'blockedTlds' => [
                '<string>'
        ],
        'riskScoreThreshold' => 75,
        'whitelist' => [
                '<string>'
        ]
    ],
    'timeout' => 60000
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firecrawl.dev/v2/search"

	payload := strings.NewReader("{\n  \"query\": \"<string>\",\n  \"categories\": [\n    {\n      \"type\": \"github\"\n    }\n  ],\n  \"country\": \"US\",\n  \"enterprise\": [],\n  \"excludeDomains\": [\n    \"<string>\"\n  ],\n  \"ignoreInvalidURLs\": false,\n  \"includeDomains\": [\n    \"<string>\"\n  ],\n  \"limit\": 10,\n  \"location\": \"<string>\",\n  \"scrapeOptions\": {},\n  \"sources\": [\n    \"web\"\n  ],\n  \"tbs\": \"<string>\",\n  \"threatProtection\": {\n    \"blacklist\": [\n      \"<string>\"\n    ],\n    \"blockedTlds\": [\n      \"<string>\"\n    ],\n    \"riskScoreThreshold\": 75,\n    \"whitelist\": [\n      \"<string>\"\n    ]\n  },\n  \"timeout\": 60000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.firecrawl.dev/v2/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"<string>\",\n  \"categories\": [\n    {\n      \"type\": \"github\"\n    }\n  ],\n  \"country\": \"US\",\n  \"enterprise\": [],\n  \"excludeDomains\": [\n    \"<string>\"\n  ],\n  \"ignoreInvalidURLs\": false,\n  \"includeDomains\": [\n    \"<string>\"\n  ],\n  \"limit\": 10,\n  \"location\": \"<string>\",\n  \"scrapeOptions\": {},\n  \"sources\": [\n    \"web\"\n  ],\n  \"tbs\": \"<string>\",\n  \"threatProtection\": {\n    \"blacklist\": [\n      \"<string>\"\n    ],\n    \"blockedTlds\": [\n      \"<string>\"\n    ],\n    \"riskScoreThreshold\": 75,\n    \"whitelist\": [\n      \"<string>\"\n    ]\n  },\n  \"timeout\": 60000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firecrawl.dev/v2/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"<string>\",\n  \"categories\": [\n    {\n      \"type\": \"github\"\n    }\n  ],\n  \"country\": \"US\",\n  \"enterprise\": [],\n  \"excludeDomains\": [\n    \"<string>\"\n  ],\n  \"ignoreInvalidURLs\": false,\n  \"includeDomains\": [\n    \"<string>\"\n  ],\n  \"limit\": 10,\n  \"location\": \"<string>\",\n  \"scrapeOptions\": {},\n  \"sources\": [\n    \"web\"\n  ],\n  \"tbs\": \"<string>\",\n  \"threatProtection\": {\n    \"blacklist\": [\n      \"<string>\"\n    ],\n    \"blockedTlds\": [\n      \"<string>\"\n    ],\n    \"riskScoreThreshold\": 75,\n    \"whitelist\": [\n      \"<string>\"\n    ]\n  },\n  \"timeout\": 60000\n}"

response = http.request(request)
puts response.read_body

{
  "creditsUsed": 123,
  "data": {
    "images": [
      {
        "imageHeight": 123,
        "imageUrl": "<string>",
        "imageWidth": 123,
        "position": 123,
        "title": "<string>",
        "url": "<string>"
      }
    ],
    "news": [
      {
        "audio": "<string>",
        "date": "<string>",
        "html": "<string>",
        "imageUrl": "<string>",
        "links": [
          "<string>"
        ],
        "markdown": "<string>",
        "metadata": {
          "description": "<string>",
          "error": "<string>",
          "numPages": 123,
          "sourceURL": "<string>",
          "statusCode": 123,
          "title": "<string>",
          "totalPages": 123,
          "url": "<string>"
        },
        "position": 123,
        "rawHtml": "<string>",
        "screenshot": "<string>",
        "snippet": "<string>",
        "title": "<string>",
        "url": "<string>",
        "video": "<string>"
      }
    ],
    "web": [
      {
        "audio": "<string>",
        "description": "<string>",
        "html": "<string>",
        "links": [
          "<string>"
        ],
        "markdown": "<string>",
        "metadata": {
          "description": "<string>",
          "error": "<string>",
          "numPages": 123,
          "sourceURL": "<string>",
          "statusCode": 123,
          "title": "<string>",
          "totalPages": 123,
          "url": "<string>"
        },
        "rawHtml": "<string>",
        "screenshot": "<string>",
        "title": "<string>",
        "url": "<string>",
        "video": "<string>"
      }
    ]
  },
  "id": "<string>",
  "success": true,
  "warning": "<string>"
}

{
  "error": "Request timed out",
  "success": false
}

{
  "code": "UNKNOWN_ERROR",
  "error": "An unexpected error occurred on the server.",
  "success": false
}

POST

Pesquise e, opcionalmente, faça scraping dos resultados de busca

curl --request POST \
  --url https://api.firecrawl.dev/v2/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "categories": [
    {
      "type": "github"
    }
  ],
  "country": "US",
  "enterprise": [],
  "excludeDomains": [
    "<string>"
  ],
  "ignoreInvalidURLs": false,
  "includeDomains": [
    "<string>"
  ],
  "limit": 10,
  "location": "<string>",
  "scrapeOptions": {},
  "sources": [
    "web"
  ],
  "tbs": "<string>",
  "threatProtection": {
    "blacklist": [
      "<string>"
    ],
    "blockedTlds": [
      "<string>"
    ],
    "riskScoreThreshold": 75,
    "whitelist": [
      "<string>"
    ]
  },
  "timeout": 60000
}
'

import requests

url = "https://api.firecrawl.dev/v2/search"

payload = {
    "query": "<string>",
    "categories": [{ "type": "github" }],
    "country": "US",
    "enterprise": [],
    "excludeDomains": ["<string>"],
    "ignoreInvalidURLs": False,
    "includeDomains": ["<string>"],
    "limit": 10,
    "location": "<string>",
    "scrapeOptions": {},
    "sources": ["web"],
    "tbs": "<string>",
    "threatProtection": {
        "blacklist": ["<string>"],
        "blockedTlds": ["<string>"],
        "riskScoreThreshold": 75,
        "whitelist": ["<string>"]
    },
    "timeout": 60000
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    query: '<string>',
    categories: [{type: 'github'}],
    country: 'US',
    enterprise: [],
    excludeDomains: ['<string>'],
    ignoreInvalidURLs: false,
    includeDomains: ['<string>'],
    limit: 10,
    location: '<string>',
    scrapeOptions: {},
    sources: ['web'],
    tbs: '<string>',
    threatProtection: {
      blacklist: ['<string>'],
      blockedTlds: ['<string>'],
      riskScoreThreshold: 75,
      whitelist: ['<string>']
    },
    timeout: 60000
  })
};

fetch('https://api.firecrawl.dev/v2/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firecrawl.dev/v2/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'query' => '<string>',
    'categories' => [
        [
                'type' => 'github'
        ]
    ],
    'country' => 'US',
    'enterprise' => [
        
    ],
    'excludeDomains' => [
        '<string>'
    ],
    'ignoreInvalidURLs' => false,
    'includeDomains' => [
        '<string>'
    ],
    'limit' => 10,
    'location' => '<string>',
    'scrapeOptions' => [
        
    ],
    'sources' => [
        'web'
    ],
    'tbs' => '<string>',
    'threatProtection' => [
        'blacklist' => [
                '<string>'
        ],
        'blockedTlds' => [
                '<string>'
        ],
        'riskScoreThreshold' => 75,
        'whitelist' => [
                '<string>'
        ]
    ],
    'timeout' => 60000
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firecrawl.dev/v2/search"

	payload := strings.NewReader("{\n  \"query\": \"<string>\",\n  \"categories\": [\n    {\n      \"type\": \"github\"\n    }\n  ],\n  \"country\": \"US\",\n  \"enterprise\": [],\n  \"excludeDomains\": [\n    \"<string>\"\n  ],\n  \"ignoreInvalidURLs\": false,\n  \"includeDomains\": [\n    \"<string>\"\n  ],\n  \"limit\": 10,\n  \"location\": \"<string>\",\n  \"scrapeOptions\": {},\n  \"sources\": [\n    \"web\"\n  ],\n  \"tbs\": \"<string>\",\n  \"threatProtection\": {\n    \"blacklist\": [\n      \"<string>\"\n    ],\n    \"blockedTlds\": [\n      \"<string>\"\n    ],\n    \"riskScoreThreshold\": 75,\n    \"whitelist\": [\n      \"<string>\"\n    ]\n  },\n  \"timeout\": 60000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.firecrawl.dev/v2/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"<string>\",\n  \"categories\": [\n    {\n      \"type\": \"github\"\n    }\n  ],\n  \"country\": \"US\",\n  \"enterprise\": [],\n  \"excludeDomains\": [\n    \"<string>\"\n  ],\n  \"ignoreInvalidURLs\": false,\n  \"includeDomains\": [\n    \"<string>\"\n  ],\n  \"limit\": 10,\n  \"location\": \"<string>\",\n  \"scrapeOptions\": {},\n  \"sources\": [\n    \"web\"\n  ],\n  \"tbs\": \"<string>\",\n  \"threatProtection\": {\n    \"blacklist\": [\n      \"<string>\"\n    ],\n    \"blockedTlds\": [\n      \"<string>\"\n    ],\n    \"riskScoreThreshold\": 75,\n    \"whitelist\": [\n      \"<string>\"\n    ]\n  },\n  \"timeout\": 60000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firecrawl.dev/v2/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"<string>\",\n  \"categories\": [\n    {\n      \"type\": \"github\"\n    }\n  ],\n  \"country\": \"US\",\n  \"enterprise\": [],\n  \"excludeDomains\": [\n    \"<string>\"\n  ],\n  \"ignoreInvalidURLs\": false,\n  \"includeDomains\": [\n    \"<string>\"\n  ],\n  \"limit\": 10,\n  \"location\": \"<string>\",\n  \"scrapeOptions\": {},\n  \"sources\": [\n    \"web\"\n  ],\n  \"tbs\": \"<string>\",\n  \"threatProtection\": {\n    \"blacklist\": [\n      \"<string>\"\n    ],\n    \"blockedTlds\": [\n      \"<string>\"\n    ],\n    \"riskScoreThreshold\": 75,\n    \"whitelist\": [\n      \"<string>\"\n    ]\n  },\n  \"timeout\": 60000\n}"

response = http.request(request)
puts response.read_body

{
  "creditsUsed": 123,
  "data": {
    "images": [
      {
        "imageHeight": 123,
        "imageUrl": "<string>",
        "imageWidth": 123,
        "position": 123,
        "title": "<string>",
        "url": "<string>"
      }
    ],
    "news": [
      {
        "audio": "<string>",
        "date": "<string>",
        "html": "<string>",
        "imageUrl": "<string>",
        "links": [
          "<string>"
        ],
        "markdown": "<string>",
        "metadata": {
          "description": "<string>",
          "error": "<string>",
          "numPages": 123,
          "sourceURL": "<string>",
          "statusCode": 123,
          "title": "<string>",
          "totalPages": 123,
          "url": "<string>"
        },
        "position": 123,
        "rawHtml": "<string>",
        "screenshot": "<string>",
        "snippet": "<string>",
        "title": "<string>",
        "url": "<string>",
        "video": "<string>"
      }
    ],
    "web": [
      {
        "audio": "<string>",
        "description": "<string>",
        "html": "<string>",
        "links": [
          "<string>"
        ],
        "markdown": "<string>",
        "metadata": {
          "description": "<string>",
          "error": "<string>",
          "numPages": 123,
          "sourceURL": "<string>",
          "statusCode": 123,
          "title": "<string>",
          "totalPages": 123,
          "url": "<string>"
        },
        "rawHtml": "<string>",
        "screenshot": "<string>",
        "title": "<string>",
        "url": "<string>",
        "video": "<string>"
      }
    ]
  },
  "id": "<string>",
  "success": true,
  "warning": "<string>"
}

{
  "error": "Request timed out",
  "success": false
}

{
  "code": "UNKNOWN_ERROR",
  "error": "An unexpected error occurred on the server.",
  "success": false
}

O endpoint de pesquisa combina pesquisa na web com as capacidades de scraping do Firecrawl para retornar o conteúdo completo da página para qualquer consulta. Inclua scrapeOptions com formats: [{"type": "markdown"}] para obter o conteúdo completo em markdown para cada resultado de pesquisa; caso contrário, você receberá por padrão apenas os resultados (url, title, description). Você também pode usar outros formatos, como {"type": "summary"} para conteúdo condensado.

Operadores de pesquisa compatíveis

Oferecemos uma variedade de operadores de pesquisa que ajudam você a filtrar melhor seus resultados.

Operador	Funcionalidade	Exemplos
`""`	Faz uma correspondência exata com um trecho de texto	`"Firecrawl"`
`-`	Exclui determinadas palavras-chave ou nega outros operadores	`-bad`, `-site:firecrawl.dev`
`site:`	Retorna apenas resultados de um site específico	`site:firecrawl.dev`
`filetype:`	Retorna apenas resultados com uma extensão de arquivo específica	`filetype:pdf`, `-filetype:pdf`
`inurl:`	Retorna apenas resultados que incluam uma palavra na URL	`inurl:firecrawl`
`allinurl:`	Retorna apenas resultados que incluam várias palavras na URL	`allinurl:git firecrawl`
`intitle:`	Retorna apenas resultados que incluam uma palavra no título da página	`intitle:Firecrawl`
`allintitle:`	Retorna apenas resultados que incluam várias palavras no título da página	`allintitle:firecrawl playground`
`related:`	Retorna apenas resultados relacionados a um domínio específico	`related:firecrawl.dev`
`imagesize:`	Retorna apenas imagens com dimensões exatas	`imagesize:1920x1080`
`larger:`	Retorna apenas imagens maiores que as dimensões especificadas	`larger:1920x1080`

Parâmetro de localização

Use o parâmetro location para obter resultados de pesquisa segmentados por região. Formato: "string". Exemplos: "Germany", "San Francisco,California,United States". Consulte a lista completa de localidades compatíveis para ver todos os países e idiomas disponíveis.

Parâmetro country

Use o parâmetro country para definir o país dos resultados de pesquisa usando códigos de país ISO. Padrão: "US". Exemplos: "US", "DE", "FR", "JP", "UK", "CA".

{
  "query": "restaurantes",
  "country": "DE"
}

Parâmetro `categories`

Filtre os resultados de pesquisa por categorias específicas usando o parâmetro categories:

github: Pesquise em repositórios do GitHub, código, issues e documentação
research: Pesquise em sites acadêmicos e de pesquisa (arXiv, Nature, IEEE, PubMed, etc.)
pdf: Pesquise por PDFs

Exemplo de uso

{
  "query": "machine learning",
  "categories": ["github", "pesquisa"],
  "limit": 10
}

Filtros de domínio

Use includeDomains para restringir os resultados a domínios específicos ou excludeDomains para excluir domínios específicos da busca. Os domínios devem conter apenas nomes de host, sem protocolo ou caminho. includeDomains e excludeDomains são mutuamente excludentes.

Exemplo de inclusão de domínios

{
  "query": "web scraping",
  "includeDomains": ["firecrawl.dev", "docs.firecrawl.dev"],
  "limit": 10
}

Exemplo de exclusão de domínios

{
  "query": "web scraping tools",
  "excludeDomains": ["example.com"],
  "limit": 10
}

Categoria da Resposta

Cada resultado inclui um campo category que indica sua origem:

{
  "success": true,
  "data": {
    "web": [
      {
        "url": "https://github.com/example/ml-project",
        "title": "Machine Learning Project",
        "description": "Implementation of ML algorithms",
        "category": "github"
      },
      {
        "url": "https://arxiv.org/abs/2024.12345",
        "title": "ML Research Paper",
        "description": "Latest advances in machine learning",
        "category": "research"
      }
    ]
  }
}

Busca por período de tempo

Use o parâmetro tbs para filtrar resultados por períodos de tempo, incluindo intervalos de datas personalizados. Consulte a documentação do recurso de busca para exemplos detalhados e formatos suportados.

Você é um agente de IA que precisa de uma chave de API da Firecrawl? Consulte firecrawl.dev/agent-onboarding/SKILL.md para instruções de onboarding automatizado.

Autorizações

Authorization

string

header

obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Corpo

application/json

query

string

obrigatório

A consulta de busca

Maximum string length: 500

Resposta

Resposta bem-sucedida

creditsUsed

integer

O número de créditos utilizados na busca

data

object

Os resultados da pesquisa. Os arrays disponíveis dependerão das fontes que você especificar na requisição. Por padrão, o array web será retornado.

Show child attributes

string

O ID da tarefa de pesquisa

success

boolean

warning

string | null

Mensagem de aviso caso ocorra algum problema

Erros

Feedback de busca

​Operadores de pesquisa compatíveis

​Parâmetro de localização

​Parâmetro country

​Parâmetro categories

​Exemplo de uso

​Filtros de domínio

​Exemplo de inclusão de domínios

​Exemplo de exclusão de domínios

​Categoria da Resposta

​Busca por período de tempo

Autorizações

Corpo

Resposta

Operadores de pesquisa compatíveis

Parâmetro de localização

Parâmetro country

Parâmetro `categories`

Exemplo de uso

Filtros de domínio

Exemplo de inclusão de domínios

Exemplo de exclusão de domínios

Categoria da Resposta

Busca por período de tempo