> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/pt-br/api-da-web/search.md).

# /search

Aprenda a usar o endpoint /search da Oxylabs Web API para pesquisar a web ao vivo e coletar resultados classificados.

O `/v1/search`  endpoint realiza buscas na web em tempo real e retorna resultados orgânicos classificados, incluindo títulos, trechos, URLs, metadados de posição e consultas relacionadas.&#x20;

Ele funciona como uma ferramenta de descoberta para identificar páginas da web confiáveis antes de enviar as URLs de destino ao endpoint [`/v1/scrape`](https://developers.oxylabs.io/products/pt-br/api-da-web/scrape.md)  para extração de páginas completas.

{% hint style="info" %}
`/v1/search`  e seus subendpoints são **somente síncronos (em tempo real)**.
{% endhint %}

## Exemplo de solicitação

O endpoint aceita um corpo de solicitação JSON com a consulta de busca **consulta**, **limites de resultados**, e parâmetros de **geolocalização** .

```bash
curl https://webapi.oxylabs.io/v1/search \
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "eu ai act compliance deadlines",
    "max_results": 3,
    "location": "DE"
  }'
```

### Parâmetros da solicitação

<table><thead><tr><th width="123">Parâmetro</th><th width="533">Descrição</th><th width="88">Tipo</th></tr></thead><tbody><tr><td><mark style="background-color:green;"><code>query</code></mark></td><td>Palavra-chave ou frase de busca (entre <code>1</code> e <code>2,048</code> caracteres).</td><td>string</td></tr><tr><td><code>max_results</code></td><td>Número de resultados de busca orgânicos a retornar (entre <code>1</code> e <code>20</code>). Padrão: <code>10</code></td><td>inteiro</td></tr><tr><td><code>location</code></td><td>Código de país ISO 3166-1 alfa-2 (por exemplo, <code>DE</code>, <code>US</code>) para buscas localizadas.</td><td>string</td></tr></tbody></table>

&#x20;    – parâmetro obrigatório.

{% hint style="warning" %}
Parâmetros desconhecidos ou escritos incorretamente são rejeitados com o código de status HTTP `400 Bad Request` , não são ignorados.
{% endhint %}

### Otimização da solicitação

<details>

<summary><strong><code>query</code></strong></summary>

Recomenda-se escrever o que uma pessoa digitaria em uma caixa de busca. Consultas em formato de palavras-chave têm resultados melhores do que consultas em formato de frase:

<table><thead><tr><th width="373">Em vez de</th><th>Use</th></tr></thead><tbody><tr><td>"Você pode me dizer quais são os prazos de conformidade da Lei de IA da UE?"</td><td><code>eu ai act compliance deadlines</code></td></tr><tr><td>"Quero saber quanto custa o Figma por licença"</td><td><code>figma pricing per seat</code></td></tr></tbody></table>

Uma pergunta por solicitação. Uma consulta composta retorna resultados que não correspondem bem a nenhuma das partes.

</details>

<details>

<summary><strong><code>max_results</code></strong></summary>

O parâmetro define um limite, não uma meta. Uma consulta com menos correspondências retorna menos resultados, ordenados do mais relevante para o menos relevante.

</details>

<details>

<summary><strong><code>location</code></strong></summary>

Preços, disponibilidade, idioma e classificações costumam variar de um país para outro.

O código ISO 3166-1 alfa-2 é o único formato aceito (por exemplo, `DE`, `US`). Um par bem formatado que não corresponda a um país atribuído é rejeitado com um `400` código de erro. Omitir o parâmetro define uma localidade `default` , que é ideal apenas quando a resposta não depende da localização.

</details>

## Exemplo de saída

{% code expandable="true" %}

```json
{
    "state": "done",
    "results": [
        {
            "title": "Cronograma de implementação | Lei de Inteligência Artificial da UE",
            "outline": [
                "Provedores: os provedores de modelos de IA de propósito geral que foram colocados no mercado antes desta data precisam estar em conformidade com a Lei de IA até 2 de agosto de 2027. ... Estados-Membros: prazo para os Estados-Membros informarem à Comissão sobre a situação dos recursos financeiros e humanos das autoridades nacionais competentes ..."
            ],
            "url": "https://artificialintelligenceact.eu/implementation-timeline/",
            "metadata": {
                "position": 1
            }
        },
        {
            "title": "Cronograma da Lei de IA da UE: principais datas e prazos de conformidade explicados",
            "outline": [
                "Enquanto a Comissão Europeia trabalha com os Estados-Membros para desenvolver a infraestrutura de comunicação e monitoramento da Lei de IA até agosto de 2025, as empresas devem se concentrar em várias áreas importantes: estabelecer um sistema de gerenciamento de riscos, implementar medidas de governança de dados, elaborar documentação técnica ..."
            ],
            "url": "https://www.dataguard.com/eu-ai-act/timeline",
            "metadata": {
                "position": 2
            }
        },
        {
            "Cronograma de implementação da Lei de IA da UE | Central de Atendimento da Lei de IA",
            "outline": [
                "A legislação da Lei de IA da UE será aplicada progressivamente, com a implementação completa das principais etapas de aplicação prevista para 2 de agosto de 2028."
            ],
            "url": "https://ai-act-service-desk.ec.europa.eu/en/ai-act/timeline/timeline-implementation-eu-ai-act",
            "metadata": {
                "position": 3
            }
        }
    ],
    "related_questions": [],
    "related_searches": [],
    "params": {
        "query": "eu ai act compliance deadlines",
        "location": "DE",
        "max_results": 3
    },
    "metadata": {
        "timestamp": 1791289627,
        "request_id": "1791289625962078444"
    }
}
```

{% endcode %}

{% hint style="warning" %}
**`outline`** é apenas um trecho representativo. Para obter dados atualizados diretamente da página, [raspe o URL](https://developers.oxylabs.io/products/pt-br/api-da-web/scrape.md).
{% endhint %}

### Dicionário de saída

<table><thead><tr><th width="237">Campo</th><th width="438.04296875">Descrição</th><th width="87.94140625">Tipo</th></tr></thead><tbody><tr><td><code>state</code></td><td><code>"done"</code> em caso de sucesso. Uma pesquisa que encontra uma falha upstream retorna <code>500</code> com <code>state: "faulted"</code> (consulte <a href="https://developers.oxylabs.io/products/pt-br/api-da-web/solucao-de-problemas.md">Códigos de erro</a>).</td><td>string</td></tr><tr><td><code>results</code></td><td>Resultados orgânicos classificados, começando pelo melhor. Sempre presente; portanto, uma saída vazia significa que nada foi encontrado.</td><td>array</td></tr><tr><td><code>results[].title</code></td><td>Título da página buscada.</td><td>string</td></tr><tr><td><code>results[].outline[]</code></td><td>Trechos dos resultados da SERP. Truncados no meio da frase.</td><td>array de strings</td></tr><tr><td><code>results[].url</code></td><td>URL absoluta do resultado. Passe para <a href="https://developers.oxylabs.io/products/pt-br/api-da-web/scrape.md"><code>/v1/scrape</code></a>.</td><td>string</td></tr><tr><td><code>results[].metadata.position</code></td><td>Posição orgânica na SERP, começando em <code>1</code>.</td><td>inteiro</td></tr><tr><td><code>related_questions</code></td><td>Objeto de pergunta de “As pessoas também perguntam” contendo <code>question</code>, <code>title</code>, e <code>snippet</code> (quando disponível).</td><td>array</td></tr><tr><td><code>related_searches</code></td><td>Consultas de pesquisa relacionadas, cada uma contendo <code>query</code>.</td><td>array</td></tr><tr><td><code>params</code></td><td>Parâmetros de execução, incluindo valores padrão.</td><td>object</td></tr><tr><td><code>metadata.timestamp</code></td><td>Timestamp Unix em segundos.</td><td>inteiro</td></tr><tr><td><code>metadata.request_id</code></td><td>Identificador de solicitação de 19 dígitos. <strong>Inclua nos chamados de suporte.</strong></td><td>string</td></tr></tbody></table>

{% hint style="info" %}
`related_searches` é útil para expandir a consulta quando a primeira pesquisa retorna poucos resultados. Ele apresenta formulações com maior cobertura.
{% endhint %}

### Endpoints de pesquisa especializados

Além da pesquisa geral na Web, há endpoints de pesquisa especializados disponíveis em `POST /v1/search/{collection}`. Eles aceitam uma `query` como `/v1/search`, mas retornam registros estruturados de um tipo de entidade, em vez de páginas da Web classificadas:

```bash
curl https://webapi.oxylabs.io/v1/search/companies \
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "new energy sector companies",
    "max_results": 3
  }'
```

<table><thead><tr><th width="163">Endpoint</th><th width="469">Retorna</th><th width="133">Entrada</th></tr></thead><tbody><tr><td><a href="https://developers.oxylabs.io/products/pt-br/api-da-web/search/company.md"><code>/search/companies</code></a></td><td>Perfis de empresas: setor, sede, número de funcionários, receita e tráfego do site.</td><td>Palavra-chave / Consulta</td></tr></tbody></table>

{% hint style="info" %}
Os endpoints de pesquisa especializados têm seus próprios parâmetros e campos de saída. Consulte a página de cada endpoint antes de reutilizar um `/v1/search` corpo da solicitação.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/pt-br/api-da-web/search.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
