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

# Parsing por IA

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

{% hint style="danger" %}
**Custa extra:** Usando parsing por IA com seus `/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 de destino. Combine `output: ["json"]` com o parâmetro de nível raiz `JSON` 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 estar em conformidade.</td><td>objeto</td></tr></tbody></table>

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

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

A Web API oferece dois mecanismos de parsing, ambos retornando os dados sob a `JSON` chave no `results[]` array:

<table><thead><tr><th width="101">Tipo</th><th>Método</th><th>Destinos</th><th>Uso 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 (ex.: <code>/scrape/amazon/product</code>, <code>/scrape/google/search</code>).</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> ou <code>json: { "schema": ... }</code> objeto.</td><td>Todas as rotas, incluindo as genéricas <code>/v1/scrape</code> e destinos sem parsers dedicados.</td><td>Schemas personalizados, layouts de página únicos ou campos fora do padrão.</td></tr></tbody></table>

{% hint style="warning" %}
Tanto os parsers pré-construídos quanto as extrações personalizadas por IA preenchem a `results[].json` chave no payload da resposta. Se você chamar um scraper dedicado (ex.: `/v1/scrape/amazon/product`) com `output: ["json"]` e usar um custom `JSON` objeto de extração, 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 uma `prompt` string ou um `schema` objeto. Não envie os dois 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 atual de venda como 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 de chave-valor planas em que os tipos de dados exatos não são rigorosamente aplicados depois

### Definido por schema (`schema`)

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

```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 busca, tabelas ou listas de produtos colocando 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 de sites diferentes em 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" mapeiam para `in_stock`, então o código subsequente ramifica com base em um único valor em vez de um grande número de correspondências de string.

### 3. Metadados de artigo e blog

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` aplica-se diretamente a 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`, a `currency` que você recebe de volta é aquela que a página decidiu mostrar.
{% endhint %}

## Schema da 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" %}
Solicitação `saída` parâmetro é 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 `nulo`.
{% 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-web/scrape/parsing-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.