> 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-web/search.md).

# /search

Aprenda a usar o endpoint /search da API Web da Oxylabs 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 ranqueados, incluindo títulos, trechos, URLs, metadados de posição e consultas relacionadas. Ele funciona como uma ferramenta de descoberta para identificar páginas da web confiáveis antes de passar URLs de destino para o [`/v1/scrape`](/products/pt-br/api-web/scrape.md) endpoint para extração completa da página.

## Exemplo de requisição

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

```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 requisiçã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>consulta</code></mark></td><td>Palavra-chave ou frase de busca (entre <code>1</code> e <code>2,048</code> caracteres).</td><td>cadeia de caracteres</td></tr><tr><td><code>max_results</code></td><td>Número de resultados 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 busca localizada.</td><td>cadeia de caracteres</td></tr></tbody></table>

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

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

### Otimização da requisição

<details>

<summary><strong><code>consulta</code></strong></summary>

Recomenda-se escrever o que uma pessoa digitaria em um campo de busca. Consultas em formato de palavra-chave superam as 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>prazos de conformidade da Lei de IA da UE</code></td></tr><tr><td>"Quero saber quanto o Figma custa por assento"</td><td><code>preço do Figma por assento</code></td></tr></tbody></table>

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

</details>

<details>

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

O parâmetro é um limite, não uma meta. Uma consulta com menos correspondências retorna menos resultados, que são ordenados do melhor para o pior.

</details>

<details>

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

Preços, disponibilidade, idioma e rankings frequentemente variam por país.

O código ISO 3166-1 alfa-2 é o único formato aceito (por exemplo, `DE`, `US`). Um par bem formado que não seja um país atribuído é rejeitado com um `400` código de erro. Omitir o parâmetro define um `padrão` locale, que é ideal apenas quando a resposta não é sensível à localização.

</details>

## Exemplo de saída

```json
{
    "state": "done",
    "results": [
        {
            "title": "Implementation Timeline | EU Artificial Intelligence Act",
            "outline": [
                "Providers: Providers of GPAI models that have been placed on the market before this date need to be compliant with the AI Act by 2 August 2027. ... Member States: Deadline for Member States to report to the Commission on the status of the financial and human resources of the national competent ..."
            ],
            "url": "https://artificialintelligenceact.eu/implementation-timeline/",
            "metadata": {
                "position": 1
            }
        },
        {
            "title": "EU AI Act Timeline: Key Compliance Dates & Deadlines Explained",
            "outline": [
                "While the EU Commission is working with member states to build out the reporting and monitoring infrastructure of the AI Act until August 2025, companies have several key areas to focus on: establishing a risk management system, implementing data governance measures, drawing up technical ..."
            ],
            "url": "https://www.dataguard.com/eu-ai-act/timeline",
            "metadata": {
                "position": 2
            }
        },
        {
            "title": "Timeline for the Implementation of the EU AI Act | AI Act Service Desk",
            "outline": [
                "The EU’s AI Act legislation applies progressively, with a full roll-out of the main application milestones foreseen by 2 August 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"
    }
}
```

{% hint style="warning" %}
**`outline`** é apenas um trecho representativo. Para obter dados ao vivo da própria página, [faça scrape da URL](/products/pt-br/api-web/scrape.md).
{% endhint %}

### Dicionário de saída

<table><thead><tr><th width="244">Campo</th><th width="404.04296875">Descrição</th><th width="95.94140625">Tipo</th></tr></thead><tbody><tr><td><code>state</code></td><td><code>"done"</code> em caso de sucesso. Uma busca que encontre uma falha upstream retorna <code>500</code> com <code>state: "faulted"</code> (veja <a href="/products/pt-br/api-web/solucao-de-problemas.md">Códigos de erro</a>).</td><td>cadeia de caracteres</td></tr><tr><td><code>results</code></td><td>Resultados orgânicos ranqueados, do melhor para o pior. Sempre presentes, então uma saída vazia significa que nada correspondeu.</td><td>vetor</td></tr><tr><td><code>results[].title</code></td><td>Título da página obtido.</td><td>cadeia de caracteres</td></tr><tr><td><code>results[].outline[]</code></td><td>Trechos de resultados da SERP. Cortados no meio da frase.</td><td>vetor de cadeias de caracteres</td></tr><tr><td><code>results[].url</code></td><td>URL absoluta do resultado. Passe para <a href="/products/pt-br/api-web/scrape.md"><code>/v1/scrape</code></a>.</td><td>cadeia de caracteres</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 do "People also ask" contendo <code>question</code>, <code>title</code>, e <code>snippet</code> (quando disponível).</td><td>vetor</td></tr><tr><td><code>related_searches</code></td><td>Consultas de pesquisa relacionadas, cada uma contendo <code>consulta</code>.</td><td>vetor</td></tr><tr><td><code>params</code></td><td>Parâmetros de execução, incluindo os valores padrão.</td><td>objeto</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 da requisição com 19 dígitos. <strong>Inclua em chamados de suporte.</strong></td><td>cadeia de caracteres</td></tr></tbody></table>

{% hint style="info" %}
`related_searches` é útil para expansão de consulta quando a primeira busca retorna poucos resultados. Ele oferece a formulação que tem mais cobertura por trás dela.
{% 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-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.