API do Scraper ChatGPT: Extraia Dados Estruturados de Mapa e Negócios Locais

TL;DR:

• O Scraper do ChatGPT (scraper.chatgpt) agora retorna um objeto map estruturado quando uma resposta do ChatGPT inclui negócios locais.
• Um POST para /api/v2/scraper/execute com um prompt de intenção local retorna lugares classificados com nome, coordenadas, endereço, telefone, site, horários, avaliação, contagem de avaliações, nível de preço e o provedor da listagem.
• Sem mais análise de prosa: os lugares que o ChatGPT menciona em uma resposta "melhores cafés perto de…" voltam como um array limpo que você pode ordenar, filtrar e armazenar.
• Os campos são anuláveis e provenientes do provedor: avaliações, horários e distância podem estar ausentes por entidade, então analise de forma defensiva.
• Comece grátis. Novas contas Scrapeless incluem créditos grátis para a API Scraper — inscreva-se em app.scrapeless.com.

Quando você faz uma pergunta local ao ChatGPT — "melhores cafés avaliados perto de Times Square" — a resposta menciona lugares reais, e até recentemente esses dados estavam bloqueados dentro da prosa. A API de Raspagem da Scrapeless agora disponibiliza como um objeto map dedicado: uma lista classificada de negócios com seu perfil completo, pronta para classificar ou monitorar. Este guia mostra como solicitá-lo, o que o objeto contém e onde os campos precisam de atenção. Cada solicitação e campo abaixo foi capturado de uma execução ao vivo do ator.

O Que Você Pode Fazer Com os Dados do Mapa do ChatGPT

O ator pega um prompt de intenção local e retorna os negócios que o ChatGPT apresenta como entidades estruturadas. Praticamente, isso permite que você:

• Acompanhe a visibilidade do pacote local — veja quais negócios o ChatGPT menciona para uma consulta "melhor X perto de Y", em que ordem, com sua avaliação e contagem de avaliações.
• Construa conjuntos de dados de localização — extraia nome, coordenadas, endereço, telefone e site para os lugares em uma resposta, os mesmos campos de perfil que uma API de locais expõe, sem raspar uma interface de mapa.
• Monitore uma marca ou concorrente — verifique se um negócio específico aparece nas recomendações locais do ChatGPT ao longo do tempo.
• Alimente sistemas downstream — passe as entidades classificadas para dashboards, mapas ou alertas como JSON limpo.

Por Que o Ator ChatGPT da Scrapeless

As respostas do ChatGPT são geradas atrás de uma interface, não servidas como um feed estruturado. O ator Scrapeless executa a consulta e retorna um envelope amigável para o desenvolvedor, para que seu código leia campos em vez de analisar regex uma resposta, acionar um navegador ou manter uma infraestrutura anti-bloqueio. O objeto map faz parte da mesma resposta que você já recebe do ator ChatGPT, junto com o texto da resposta, resultados da pesquisa e produtos.

Endpoint e Parâmetros

O ator é executado no endpoint da API Scraper síncrona. Autentique-se com seu token no cabeçalho x-api-token.

• Endpoint: POST https://api.scrapeless.com/api/v2/scraper/execute
• Ator: scraper.chatgpt

O objeto map aparece no task_result quando a resposta contém negócios locais; um prompt não local retorna um map vazio.

Solicitação Autenticada

Uma solicitação mínima se parece com isto (ilustrativo — substitua o token):

curl 'https://api.scrapeless.com/api/v2/scraper/execute' \
  --header 'Content-Type: application/json' \
  --header 'x-api-token: SEU_TOKEN_API' \
  --data '{
    "actor": "scraper.chatgpt",
    "input": {
      "prompt": "melhores cafés avaliados perto de Times Square Nova Iorque",
      "country": "US",
      "web_search": true
    }
  }'

Integração em Python

Este exemplo lê o token da variável de ambiente SCRAPELESS_API_KEY, envia uma consulta local e imprime os lugares classificados do objeto map. Ele usa apenas a biblioteca padrão do Python.

import json
import os
import urllib.request

API_URL = "https://api.scrapeless.com/api/v2/scraper/execute"
API_TOKEN = os.environ["SCRAPELESS_API_KEY"]

payload = {
    "actor": "scraper.chatgpt",
    "input": {
        "prompt": "melhores cafés avaliados perto de Times Square Nova Iorque",
        "country": "US",
        "web_search": True,
    },
}

request = urllib.request.Request(
    API_URL,
    data=json.dumps(payload).encode("utf-8"),
    headers={"Content-Type": "application/json", "x-api-token": API_TOKEN},
    method="POST",
)

with urllib.request.urlopen(request, timeout=180) as response:

data = json.loads(response.read().decode("utf-8"))

result = data.get("task_result", {})
entities = (result.get("map") or {}).get("entities") or []

print("status:", data.get("status"))
print("map entities:", len(entities))

for place in entities[:5]:
    inner = place.get("entity", {})
    print("-", place.get("name"))
    print("   avaliação:", inner.get("rating"), "| avaliações:", inner.get("review_count"), "| preço:", inner.get("price_str"))
    print("   endereço:", inner.get("address"))

O Objeto Mapa

O objeto map está em task_result e contém uma lista de entities ordenada, além de uma lista de raw_search_entities não ordenada. Os campos abaixo são os que você mais usará; os valores são um exemplo ilustrativo de uma execução ao vivo, reduzidos para comprimento.

// Exemplo ilustrativo de uma execução ao vivo do scraper.chatgpt — os nomes dos campos são reais, os valores reduzidos.
{
  "status": "success",
  "task_result": {
    "map": {
      "entities": [
        {
          "name": "Frisson Espresso",
          "category": "coffee_shop",
          "latitude": 40.760837,
          "longitude": -73.9889995,
          "entity": {
            "address": "326 W 47th St, New York, NY 10036, Estados Unidos",
            "phone": "+1 646-850-3928",
            "website_url": "<site do negócio>",
            "hours": [{ "day": 5, "start": "0700", "end": "1800" }],
            "is_open": false,
            "categories": ["Cafeteria", "Café", "Bar de Espresso"],
            "rating": 4.6,
            "review_count": 1006,
            "price_str": "$",
            "provider": "yelp-feed",
            "provider_url": "<URL de listagem do provedor>",
            "distance_meters": null
          }
        }
      ],
      "raw_search_entities": []
    }
  }
}

Uma consulta ao vivo para cafés perto da Times Square retornou oito lugares ranqueados; o resultado mais alto, Frisson Espresso, teve uma avaliação de 4.6 sobre 1.006 avaliações, um nível de preço de $, horários completos de funcionamento e seu provedor de listagem anexado.

Problemas Comuns de Formato de Dados

• map está vazio para prompts não locais. O objeto só é preenchido quando a resposta contém negócios. Se você receber um map vazio, a consulta não tinha intenção local - adicione um lugar ao prompt e habilite web_search.
• O perfil do lugar está aninhado em um nível abaixo. Os campos de classificação (name, latitude, longitude, category) estão na entidade, mas os campos de contato e perfil vivem sob entity.*. Leia place["entity"]["rating"], não place["rating"].
• Os campos são fonte do provedor e podem ser nulos. distance_meters, hours e até mesmo rating podem ser nulos para uma entidade específica dependendo do provedor, então proteja-se antes de usá-los.
• Use raw_search_entities para recuperação. A lista de entities ranqueadas é o que o ChatGPT levantou; raw_search_entities contém candidatos adicionais quando você precisa de uma cobertura mais ampla.

Atores Acompanhantes

O objeto map é uma parte da resposta do ChatGPT, que também carrega o texto da resposta, search_result e products. A mesma forma de requisição cobre os outros motores de resposta - troque scraper.chatgpt por scraper.gemini, scraper.perplexity e o restante. A Scrapeless publica um repositório de exemplo do scraper do ChatGPT de código aberto com código executável, e para o envelope completo da resposta veja o guia da API do Scraper do ChatGPT.

Conclusão

O objeto map do ChatGPT Scraper transforma uma recomendação conversacional local em dados estruturados: envie um prompt de intenção local, leia uma lista classificada de empresas com coordenadas, detalhes de contato, horários, classificação e provedor. Lembre-se de que os campos de perfil estão aninhados sob entity, que alguns campos podem ser nulos e que um prompt não local retorna um mapa vazio. Os dados de locais subjacentes são obtidos de provedores como Yelp, e a estrutura da resposta circundante está documentada na referência do ator ChatGPT.

Pronto para capturar os dados locais do ChatGPT? Comece gratuitamente no painel do Scrapeless, veja onde o ator se encaixa na página do produto API de Scraping ou compare planos em preços do Scrapeless.

FAQ

Q: O que é o objeto de mapa do ChatGPT?
A: É um campo estruturado na resposta scraper.chatgpt que lista os negócios locais que o ChatGPT apresenta para uma consulta — cada um com nome, coordenadas, endereço, telefone, site, horários, classificação, contagem de avaliações, nível de preço e o provedor da listagem.

Q: Como faço para que o objeto de mapa seja preenchido?
A: Envie um prompt com intenção local (uma pergunta no estilo "melhor X perto de Y") e habilite web_search. Um prompt não local retorna um map vazio.

Q: Qual endpoint e parâmetros ele usa?
A: POST https://api.scrapeless.com/api/v2/scraper/execute com actor definido como scraper.chatgpt e um objeto input contendo prompt, country e opcionalmente web_search. Autentique-se com seu token em x-api-token.

Q: Onde estão a classificação e o endereço na resposta?
A: Campos de classificação como name e coordenadas estão na entidade, mas campos de contato e perfil — address, phone, rating, review_count, hours — vivem sob entity.*. Leia place["entity"]["rating"].

Q: Os campos estão sempre presentes?
A: Não. Os valores são de provedores, portanto distance_meters, hours e rating podem ser nulos para uma determinada entidade. Proteja-se contra valores ausentes antes de usá-los.

Q: Posso usar o mesmo código para outros assistentes de IA?
A: Sim. O ator ChatGPT compartilha a forma de solicitação do LLM Chat Scraper, então trocar scraper.chatgpt por scraper.gemini ou scraper.perplexity reutiliza a mesma integração.