API de Scraping Local do Google: Transforme o Pacote Local em JSON

Principais Conclusões:

• Uma solicitação, um ator. A API Scrapeless Scraper transforma o pacote local do Google em um único POST contra o ator scraper.google.search. Sem navegador para manipular, sem marcação para analisar.
• tbm: "lcl" é o interruptor. Envie a entrada { "q": "cafés em San Francisco", "tbm": "lcl" } e o ator retorna as listagens de negócios com suporte a mapas em vez do SERP da web.
• Campos estruturados, não HTML bruto. A resposta é um objeto local analisado — local_results.places[] com títulos, classificações, contagens de revisão, endereços, faixas de preços e miniaturas de fotos — planificados no nível superior.
• Os filtros também vêm. suggested_searches traz as opções "Aberto agora / Melhor avaliado / Barato" como URLs do Google prontas para seguir, para que você possa pivotar a mesma consulta sem reconstruí-la.
• Sem proxy, sem manipulação de anti-bots do seu lado. Egressos residenciais, geo-roteamento e renderização ocorrem no lado do servidor; você envia a consulta e lê JSON.
• Gratuito para começar. Novas contas Scrapeless incluem créditos gratuitos da API Scraper — inscreva-se em app.scrapeless.com.

Introdução: transforme o pacote local do Google em JSON

O pacote local do Google é o conjunto de listagens de negócios que aparece no topo de uma pesquisa local — os cartões com suporte a mapas que o Google exibe quando alguém procura "cafés em San Francisco" ou "encanadores perto de mim." Cada cartão contém um nome, uma categoria, uma classificação por estrelas, uma contagem de avaliações, um endereço e uma faixa de preço. É a superfície que as buscas com intenção local realmente clicam, o que o torna o conjunto de dados por trás de muito trabalho prático:

• Rastreamento de classificação local — veja quais negócios ocupam as posições de 1 a N para uma consulta em uma determinada cidade.
• Monitoramento competitivo — acompanhe a classificação e a contagem de avaliações de um concorrente ao longo do tempo.
• Listas de leads — extraia os negócios que classificam para uma consulta de categoria mais localidade em uma tabela estruturada.
• Amostragem de avaliações e sentimentos — cada cartão apresenta um trecho representativo de avaliação que você pode coletar em grande escala.
• Dimensionamento de mercado — conte quantos negócios de um tipo se classificam em uma área metropolitana e como suas classificações se agrupam.

Extrair esse pacote manualmente significa renderizar uma página de pesquisa com muito JavaScript, passar pelas limitações de taxa do Google e escrever seletores contra marcações que mudam. A API Scraper faz tudo isso no lado do servidor e fornece o objeto analisado.

Por que a API Scraper

Um scraper local tradicional é três funções coladas: passar pela camada de anti-bots, renderizar a página e analisar os cartões. A API Scrapeless Scraper as colapsa em uma única chamada. Você nomeia o ator scraper.google.search, fornece uma consulta e tbm: "lcl", e recebe de volta o pacote local analisado.

• Sem navegador, sem parser para manter. O ator renderiza e analisa os resultados locais do Google; você recebe campos, não um DOM para percorrer.
• Egressos residenciais e geo-roteamento estão embutidos. Você envia a string da consulta; o ator lida com a camada da rede e a renderização JavaScript.
• Uma chave, uma forma. Um único x-api-token autentica a chamada, e o pacote local sempre volta na mesma forma analisada, então um cliente escrito uma vez é reutilizado em consultas e cidades.

Obtenha sua chave da API no plano gratuito em app.scrapeless.com. O pacote local do Google está dentro da família Deep SerpApi ao lado das outras superfícies de pesquisa do Google no catálogo de preços.

Pré-requisitos

• Uma conta Scrapeless e chave da API — inscreva-se em app.scrapeless.com.
• curl para o teste rápido, ou Python 3.10+ para o cliente abaixo.
• Familiaridade básica com HTTP e JSON.

Armazene sua chave no ambiente para que nunca chegue ao código:

export SCRAPELESS_API_KEY=your_api_token_here

A solicitação

O pacote local usa o endpoint da API Scraper v1 e o ator de pesquisa do Google. Selecionar o pacote local é um campo de entrada — tbm configurado para lcl.

• Endpoint: POST https://api.scrapeless.com/api/v1/scraper/request
• Autenticação: cabeçalho x-api-token: $SCRAPELESS_API_KEY
• Ator: scraper.google.search (tbm: "lcl" seleciona o pacote local em vez do SERP da web)

O corpo da solicitação é { "actor": "<nome>", "input": { … } }:

{
  "actor": "scraper.google.search",
  "input": { "q": "cafés em San Francisco", "tbm": "lcl" }
}

Exemplo

A verificação mais rápida é um curl. Ele envia o ator e a entrada, e imprime o objeto local analisado:

curl -sS -X POST https://api.scrapeless.com/api/v1/scraper/request \
  -H "Content-Type: application/json" \
  -H "x-api-token: $SCRAPELESS_API_KEY" \
  -d '{
    "actor": "scraper.google.search",
    "input": { "q": "cafés em San Francisco", "tbm": "lcl" }
  }'

A mesma chamada em Python lê a chave do ambiente e retorna a resposta analisada:

import os
import json
import requests

ENDPOINT = "https://api.scrapeless.com/api/v1/scraper/request"


def scrape_local(query: str) -> dict:
    resp = requests.post(
        ENDPOINT,
        headers={
            "Content-Type": "application/json",
            "x-api-token": os.environ["SCRAPELESS_API_KEY"],
        },
        json={"actor": "scraper.google.search", "input": {"q": query, "tbm": "lcl"}},
        timeout=120,
    )
    resp.raise_for_status()
    return resp.json()


if __name__ == "__main__":
    data = scrape_local("cafés em San Francisco")
    for place in data["local_results"]["places"]:
        print(place["position"], place["title"], place["rating"], place["address"])

scraper.google.search achata o pacote local analisado no nível superior — não há um invólucro result para descompactar. Leia local_results.places[] diretamente.

Obtenha sua chave de API no plano gratuito: app.scrapeless.com

O Que Você Recebe de Volta

O ator retorna o objeto local analisado diretamente, ao lado de um envelope metadata que aponta para o HTML renderizado armazenado. A execução capturada para q: "cafés em San Francisco", tbm: "lcl" retornou 20 lugares classificados:

// Forma de nível superior de uma execução ao vivo do scraper.google.search (tbm: "lcl").
// miniatura base64 e a maioria das entradas de places[] cortadas; os valores dos campos são reais.
{
  "local_results": {
    "places": [
      {
        "position": 1,
        "title": "The Coffee Berry SF",
        "type": " Café",
        "rating": 4.9,
        "reviews": 588,
        "reviews_original": "(588)",
        "price": "$",
        "address": "1410 Lombard St",
        "phone": " $1–10 ",
        "hours": "4.9(588) ",
        "extensions": ["O espresso era delicioso e a equipe era muito simpática e acolhedora."],
        "thumbnail": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABA…",
        "place_id": "",
        "place_id_search": "",
        "lsig": "",
        "gps_coordinates": { "latitude": 0, "longitude": 0 }
      },
      {
        "position": 8,
        "title": "Delah Coffee",
        "type": " Café",
        "rating": 4.7,
        "reviews": 1100,
        "reviews_original": "(1.1K)",
        "price": "$",
        "address": "370 4th St",
        "phone": "Retirada na calçada",
        "hours": "Comer no local",
        "extensions": ["Comer no local", "Retirada na calçada", "Entrega sem contato"],
        "thumbnail": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABA…",
        "place_id": "",
        "place_id_search": "",
        "lsig": "",
        "gps_coordinates": { "latitude": 0, "longitude": 0 }
      }
    ]
  },
  "search_information": {
    "query_displayed": "cafés em San Francisco",
    "organic_results_state": "Resultados para a grafia exata",
    "total_results": 0,
    "time_taken_displayed": ""
  },
  "suggested_searches": [
    {
      "name": "Aberto agora",
      "q": "cafés abertos agora em San Francisco",
      "link": "https://www.google.com/search?…&udm=1&q=cafés+em+San+Francisco+abertos+agora",
      "uds": "",
      "thumbnail": ""
    }
  ],
  "pagination": {},
  "metadata": {
    "engine": "google.search",
    "rawUrl": "https://api.scrapeless.com/storage/scrapeless.scraper.google.search/…html"
  }
}

Os campos em cada cartão places[]:

As chaves de nível superior ao redor dos cartões:

Algumas observações honestas da forma capturada:

• O objeto é achatado. local_results.places[] é a matriz pela qual você itera — não há um wrapper result, ao contrário de alguns outros atores.
• reviews e reviews_original carregam a mesma contagem de duas maneiras. Um é um inteiro para matemática, o outro é a string de exibição do Google ((3.4K)). Leia o que sua pipeline precisar.
• phone e hours rastreiam o que o Google renderiza em cada slot de cartão. Para muitos cartões locais, isso é uma faixa de preço (" $1–10 ") ou uma bandeira de serviço (Retirada na calçada, Refeição no local) em vez de um número de telefone literal ou horários de abertura. Trate ambos como texto livre e valide antes de confiar neles.
• extensions ramifica por cartão. A maioria dos cartões retorna um único trecho de revisão; cartões com opções de pedido retornam a lista de serviços (Refeição no local, Retirada na calçada, Entrega sem contato). Verifique qual você recebeu.
• Os campos de identificador e coordenadas podem voltar vazios. place_id, place_id_search, lsig e gps_coordinates estão presentes no esquema, mas podem estar vazios ou zero por cartão — trate campos ausentes como anuláveis.
• metadata.rawUrl é sua saída de emergência. Ele armazena o HTML renderizado se você precisar de um campo que o objeto analisado não exiba.

Conclusão

Capturar o pacote local do Google se resume a uma decisão e uma solicitação: escolha o ator scraper.google.search, envie { "q": "<query>", "tbm": "lcl" } com seu x-api-token e leia local_results.places[] de volta como JSON analisado. A rotação de proxy, a renderização em JavaScript e a análise ocorrem no lado do servidor, portanto, o mesmo cliente pode apontar para qualquer cidade ou categoria mudando a string da consulta. Para o lado das respostas de IA da busca do Google, o guia de captura do Google AI Overview orienta sobre como capturar o bloco de resposta e suas citações da mesma forma. Fixe a localidade em q, mantenha tbm: "lcl" configurado e trate os campos de texto livre e identificador como anuláveis.

Pronto para construir seu pipeline de busca local com inteligência artificial?

Junte-se à nossa comunidade para reivindicar um plano gratuito e se conectar com desenvolvedores que estão criando pipelines de busca local: Discord · Telegram.

Inscreva-se em app.scrapeless.com para créditos gratuitos da Scraper API e aponte o ator scraper.google.search para as consultas, cidades e categorias que sua pipeline precisa.

FAQ

P: É legal capturar dados do Google Local?

O pacote local é um dado visivelmente público. As regras variam por jurisdição e pelos termos de serviço do Google, portanto, revise os ToS relevantes e consulte um advogado para seu caso de uso antes de operar em grande escala. Nunca colete dados pessoais protegidos sob o GDPR ou CCPA.

P: Preciso de um proxy?

Não. Egressos residenciais e geo-roteamento estão embutidos no ator — você envia a consulta, o ator cuida da camada de rede e da renderização.

P: O que faz tbm: "lcl"?

Ele seleciona o pacote Local do Google — os listagens comerciais com suporte de mapa — em vez do SERP da web. Omitir ou alterá-lo e o mesmo ator retorna os resultados orgânicos da web para a consulta.

P: Quantos lugares são retornados?

O ator retorna os cartões que o Google classifica para a consulta; a execução capturada para "cafés em San Francisco" retornou 20. A contagem varia por consulta, categoria e localidade.

P: Como faço para direcionar uma cidade diferente?

Coloque a localidade em q. O ator lê a string da consulta, então cafés em Austin ou encanadores em Chicago retornam o pacote local para essa área.

P: Onde está o HTML bruto se algum campo estiver ausente?

metadata.rawUrl armazena uma cópia da página renderizada. Use-o para analisar qualquer campo que o ator não exiba no objeto analisado.

P: Posso rodar isso sem um agente de IA ou SDK?

Sim. É HTTP puro — curl, requests do Python, fetch do Node ou qualquer cliente HTTP funciona diretamente. Nenhum SDK é necessário.