> 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/scrape/analise-por-ia.md).

# Análise por IA

Extraia JSON estruturado de qualquer página em uma única requisição da Web API, usando um prompt em linguagem natural ou uma definição de JSON Schema.

{% hint style="danger" %}
**Custa extra:** Usar análise de IA com suas `/scrape` solicitações usa significativamente mais crédito da conta.
{% endhint %}

A Web API fornece extração estruturada de JSON na mesma chamada HTTP que busca a página web de destino. Combine `output: ["json"]` com o root-level `json` parâmetro para extrair campos personalizados usando prompts em linguagem natural ou definições rígidas de OpenAPI / JSON Schema.

<table><thead><tr><th width="143">Campo</th><th>Descrição</th><th width="85">Tipo</th></tr></thead><tbody><tr><td><code>json.prompt</code></td><td>Descrição em linguagem natural dos campos a extrair.</td><td>cadeia de caracteres</td></tr><tr><td><code>json.schema</code></td><td>Um <a href="https://spec.openapis.org/oas/v3.1.0#schema-object">OpenAPI Schema Object</a> ao qual o resultado deve obedecer.</td><td>objeto</td></tr></tbody></table>

{% hint style="success" %}
Use `prompt` ao explorar uma página e você ainda não conhece sua estrutura. Use `schema` quando a saída alimenta código, e uma chave renomeada ou ausente o quebraria.
{% endhint %}

## Parsers dedicados vs. extração personalizada por IA

A Web API oferece suporte a dois mecanismos de análise, ambos retornando dados sob a `json` chave na `results[]` array:

<table><thead><tr><th width="101">Tipo</th><th>Método</th><th>Destinos</th><th>Use para</th></tr></thead><tbody><tr><td>Parser integrado</td><td>Defina <code>output: ["json"]</code> sem fornecer um root <code>json</code> objeto.</td><td>Destinos dedicados com parsers pré-construídos (por exemplo, <code>/scrape/amazon/product</code>, <code>/scrape/google/search</code>) e selecione destinos usando <code>/v1/scrape</code> (por exemplo, páginas de produto da Bed Bath &#x26; Beyond) </td><td>Schemas padronizados de e-commerce e SERP mantidos pela Oxylabs.</td></tr><tr><td>Extração personalizada por IA</td><td>Defina <code>output: ["json"]</code> e passe <code>json: { "prompt": ... }</code> or <code>json: { "schema": ... }</code> objeto.</td><td>Todas as rotas, incluindo genéricas <code>/v1/scrape</code> e destinos sem parsers dedicados.</td><td>Schemas personalizados, layouts de página exclusivos ou campos não padronizados.</td></tr></tbody></table>

{% hint style="warning" %}
Tanto parsers pré-construídos quanto extrações personalizadas por IA preenchem a `results[].json` chave no payload da resposta. Se você chamar um scraper dedicado (por exemplo, `/v1/scrape/amazon/product` ) com `output: ["json"]` e usar um `json` objeto de extração personalizado, a extração personalizada por IA substituirá a saída do parser integrado. Escolha uma opção por solicitação.
{% endhint %}

## Modos de extração: `prompt` vs. `schema`

Ao usar extração personalizada por IA, o root `json` objeto aceita um `prompt` string ou um `schema` objeto. Não passe ambos os parâmetros na mesma solicitação.

### Linguagem natural (`prompt`)

Passe uma instrução em linguagem natural descrevendo os campos desejados. O modelo de IA inspeciona o DOM da página e constrói um objeto JSON correspondente.

```json
{
  "url": "https://example.com/product/10928",
  "output": ["json"],
  "json": {
    "prompt": "Extraia o título principal do produto, o preço de venda atual como um número, o código da moeda e uma lista de URLs de imagens."
  }
}
```

#### Quando usar

* Prototipagem rápida
* Extração experimental de dados
* Extrações simples e planas de chave-valor em que os tipos de dados exatos não são estritamente exigidos depois

### Definido por schema (`schema`)

Passe um objeto JSON Schema em conformidade com a especificação de Schema do OpenAPI 3.1 / OAS 3.0. O pipeline de extração garante que a resposta corresponda aos tipos, estruturas aninhadas e campos obrigatórios definidos.

```json
{
  "url": "https://example.com/product/10928",
  "output": ["json"],
  "json": {
    "schema": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "price": { 
          "type": "number", 
          "description": "O preço final com desconto mostrado ao usuário, sem impostos." 
        },
        "currency": { "type": "string" },
        "in_stock": { "type": "boolean" },
        "categories": {
          "type": "array",
          "items": { "type": "string" }
        }
      },
      "required": ["title", "price", "currency", "in_stock"]
    }
  }
}
```

#### Quando usar:&#x20;

* Pipelines de produção
* Bancos de dados de ingestão automatizada
* Aplicações fortemente tipadas em que tipos de dados ausentes ou inesperados podem causar erros

## Padrões comuns de schema

### 1. Linhas e listas repetidas

Extraia resultados de pesquisa, tabelas ou listagens de produtos envolvendo um objeto de linha em um array:

```json
{
  "url": "https://example.com/search?q=laptop",
  "output": ["json"],
  "json": {
    "schema": {
      "type": "object",
      "properties": {
        "products": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "price": { "type": "number" },
              "rating": { "type": "number", "nullable": true },
              "url": { 
                "type": "string", 
                "description": "URL absoluta para a página de detalhes do produto" 
              }
            },
            "required": ["name", "price", "url"]
          }
        }
      },
      "required": ["products"]
    }
  }
}
```

### 2. enum padronizado e registros aninhados

Mapeie textos diferentes em sites diferentes para vocabulários internos fixos usando `enum`:

```json
{
  "url": "https://example.com/product/123",
  "output": ["json"],
  "json": {
    "schema": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "availability": {
          "type": "string",
          "enum": ["in_stock", "out_of_stock", "preorder", "discontinued"],
          "description": "Mapeie a redação da página para uma destas strings de estado padronizadas"
        },
        "seller": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "rating": { "type": "number", "nullable": true }
          },
          "required": ["name"]
        }
      },
      "required": ["title", "availability"]
    }
  }
}
```

Por exemplo, `enum` é o que torna o campo comparável entre sites: "Em estoque", "Disponível agora" e "Envia hoje" todos caem em `in_stock`, então o código subsequente faz ramificações com base em um único valor em vez de em um grande número de correspondências de string.

### 3. Metadados de artigos e blogs

Extraia metadados de publicação para armazenamento estruturado em banco de dados:

```json
{
  "url": "https://example.com/blog/article",
  "output": ["json"],
  "json": {
    "schema": {
      "type": "object",
      "properties": {
        "headline": { "type": "string" },
        "author": { "type": "string", "nullable": true },
        "published_at": {
          "type": "string",
          "description": "Data de publicação formatada como uma string ISO 8601 (YYYY-MM-DD)"
        },
        "tags": { "type": "array", "items": { "type": "string" } }
      },
      "required": ["headline", "published_at"]
    }
  }
}
```

## Extração localizada

`location` se aplica diretamente às extrações por IA. Passe códigos de país ISO 3166-1 alpha-2 para garantir que preços e moedas localizados sejam extraídos corretamente:

```bash
curl https://webapi.oxylabs.io/v1/scrape \
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://sandbox.oxylabs.io/products/1",
    "output": ["json"],
    "location": "DE",
    "json": {
      "schema": {
        "type": "object",
        "properties": {
          "price": { "type": "number" },
          "currency": { "type": "string" }
        },
        "required": ["price", "currency"]
      }
    }
  }'
```

{% hint style="info" %}
Sem `location`, o `currency` valor que você recebe de volta é aquele que a página decidiu mostrar.
{% endhint %}

## Esquema de resposta

O JSON extraído é retornado dentro do envelope padrão em `results[].json`:

{% code expandable="true" %}

```json
{
  "state": "done",
  "results": [
    {
      "json": {
        "currency": "€",
        "price": 91.99
      },
      "metadata": {
        "page": 1,
        "run_js": false,
        "url": "https://sandbox.oxylabs.io/products/1",
        "statuses": {
          "http_request": {
            "code": 200,
            "tag": "HTTP_OK"
          },
          "json_parse": {
            "code": 12000,
            "tag": "PARSE_SUCCESS"
          }
        }
      }
    }
  ],
  "params": {
    "url": "https://sandbox.oxylabs.io/products/1",
    "output": [
      "json"
    ],
    "json": {
      "schema": {
        "properties": {
          "currency": {
            "type": "string"
          },
          "price": {
            "type": "number"
          }
        },
        "required": [
          "price",
          "currency"
        ],
        "type": "object"
      },
      "prompt": null
    },
    "location": "DE",
    "device": "desktop",
    "run_js": null
  },
  "metadata": {
    "timestamp": 1790854381,
    "request_id": "7511387695155825665"
  }
}
```

{% endcode %}

{% hint style="info" %}
Requisição `output` é uma lista. Você pode solicitar `output: ["json", "markdown"]` em uma única solicitação para receber tanto os campos extraídos quanto o texto completo. As chaves de formato não solicitadas retornam `null`.
{% endhint %}

### Exemplos de código

{% tabs %}
{% tab title="Python (baseado em schema)" %}

```python
import os
import json
import requests

API_URL = "https://webapi.oxylabs.io/v1/scrape"
HEADERS = {
    "Authorization": f"Bearer {os.environ['OXYLABS_WEB_API_KEY']}",
    "Content-Type": "application/json"
}

extraction_schema = {
    "type": "object",
    "properties": {
        "headline": {"type": "string"},
        "author": {"type": "string", "nullable": True},
        "publish_date": {
            "type": "string", 
            "description": "String de data de publicação formatada em ISO 8601 (YYYY-MM-DD)."
        },
        "word_count": {"type": "integer"}
    },
    "required": ["headline", "publish_date"]
}

payload = {
    "url": "https://example.com/blog/article-1",
    "output": ["json"],
    "json": {
        "schema": extraction_schema
    }
}

response = requests.post(API_URL, headers=HEADERS, json=payload, timeout=120)
response.raise_for_status()

parsed_data = response.json()["results"][0]["json"]
print(json.dumps(parsed_data, indent=2))
```

{% endtab %}

{% tab title="Node.js (baseado em prompt)" %}

```javascript
const API_URL = "https://webapi.oxylabs.io/v1/scrape";
const HEADERS = {
  "Authorization": `Bearer ${process.env.OXYLABS_WEB_API_KEY}`,
  "Content-Type": "application/json"
};

const payload = {
  url: "https://example.com/product/10928",
  output: ["json"],
  json: {
    prompt: "Extraia o título do produto, a classificação em estrelas de 5 pontos, a contagem de avaliações e os principais recursos."
  }
};

async function executeAiExtraction() {
  const response = await fetch(API_URL, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify(payload)
  });

  if (!response.ok) {
    throw new Error(`HTTP Error ${response.status}: ${await response.text()}`);
  }

  const data = await response.json();
  const extractedJson = data.results[0].json;
  console.log("Dados extraídos:", JSON.stringify(extractedJson, null, 2));
}

executeAiExtraction();
```

{% endtab %}
{% endtabs %}


---

# 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/scrape/analise-por-ia.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.
