Pular para o conteúdo

Coletas · POST /v1/exports

Exportações

Transforme os lugares de uma coleta em um arquivo csv, json ou xlsx, com um link de download que funciona sem chave de API.

Crie uma exportação

Mande o id da coleta e um format: csv, json ou xlsx. Sem o formato, vem csv. Criar uma exportação é de graça, e a coleta pode ainda estar rodando: o arquivo traz os lugares que ela tinha naquele momento.

curl -X POST https://api.gmaps.dev/v1/exports \
  -H "Authorization: Bearer $GMAPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collectionId": "8c1f5e2a-7b3d-4f60-9e14-2a6d0b9c7f31",
    "format": "csv"
  }'

A resposta vem com status 201:

{
  "data": {
    "id": "e41d7c90-3a5b-4f28-8c61-0b9e2d4a7f15",
    "collectionId": "8c1f5e2a-7b3d-4f60-9e14-2a6d0b9c7f31",
    "format": "csv",
    "locale": "pt-BR",
    "rows": 140,
    "url": "https://api.gmaps.dev/v1/exports/e41d7c90-3a5b-4f28-8c61-0b9e2d4a7f15/download?token=q3Xr0bVh6YkL2mN8pT4sW1zA9cE5dF7g",
    "createdAt": "2026-09-24T15:30:00.000Z",
    "expiresAt": "2026-09-25T15:30:00.000Z"
  }
}
  • url: abre o arquivo sem chave até o expiresAt. Qualquer pessoa com o link consegue abrir, então trate o link como uma senha.
  • expiresAt: 24 horas depois de você criar a exportação.
  • rows: quantos lugares a coleta tinha quando você criou a exportação. O arquivo pode ter menos se, desde então, uma empresa pediu para ficar de fora.

Baixe o arquivo

Abra o link no navegador, numa planilha ou no seu código, quantas vezes quiser até ele expirar. Baixar também é de graça:

curl -o places.csv "https://api.gmaps.dev/v1/exports/e41d7c90-3a5b-4f28-8c61-0b9e2d4a7f15/download?token=q3Xr0bVh6YkL2mN8pT4sW1zA9cE5dF7g"

Montamos o arquivo cada vez que o link é aberto, com os lugares que a coleta tinha quando você criou a exportação. Um lugar cuja empresa pediu para ficar de fora depois disso não entra.

Para ver a exportação de novo, com o link, chame GET /v1/exports/{id}. Quando o link expira, ou os lugares da coleta são apagados, os dois respondem 404 EXPORT_NOT_FOUND: crie uma nova exportação a partir da coleta.

Formatos

  • csv: uma linha por lugar, sem limite de tamanho. Vem em UTF-8, com a marcação que faz o Excel mostrar os acentos direito. Uma lista, como vários telefones, fica numa célula só, separada por vírgulas. Uma célula que começa como fórmula ganha um ' na frente, para a planilha mostrar como texto em vez de executar a fórmula.
  • json: um array com um objeto por lugar. As chaves são as da tabela abaixo, iguais em qualquer idioma. Listas continuam listas, e um valor que falta vem como null.
  • xlsx: uma aba, com uma linha por lugar, até 50.000 lugares. Uma coleta maior é recusada com 400 VALIDATION_ERROR: nesse caso, exporte em csv.

O locale escolhe o idioma dos nomes das colunas no csv e no xlsx: en, es ou pt-BR. Sem ele, vale o idioma da sua conta. Ele não traduz os lugares: cada um fica no idioma da última busca que o coletou.

Colunas

Todos os formatos têm as mesmas colunas, nesta ordem. A extensão gratuita para Chrome grava as mesmas, então o código que lê um arquivo lê o outro:

Chave no jsonCabeçalho em inglêsCabeçalho em portuguêsCabeçalho em espanhol
nameNameNomeNombre
phonesPhonesTelefonesTeléfonos
emailsEmailsE-mailsCorreos electrónicos
statusStatusStatusSituación
cityCityCidadeCiudad
stateStateEstadoEstado
sectorSectorSetorSector
websiteWebsiteSiteSitio web
addressAddressEndereçoDirección
ratingGoogle ratingNota no GoogleCalificación en Google
reviewCountGoogle reviewsAvaliações no GoogleReseñas en Google
cidGoogle CIDCID do GoogleCID de Google
placeIdGoogle place IDID do lugar no GoogleID del lugar en Google
mapsUrlGoogle Maps URLURL do Google MapsURL de Google Maps
latitudeLatitudeLatitudeLatitud
longitudeLongitudeLongitudeLongitud
plusCodePlus codePlus codePlus code
scrapedAtCollected atData da coletaFecha de recopilación
  • A coluna emails fica vazia se a sua conta não podia ler e-mails quando você criou a exportação. Ela também fica vazia num lugar para o qual não temos e-mail. Veja E-mails.
  • No xlsx, o cid é gravado como texto. Se abrir o csv numa planilha, importe essa coluna como texto, senão os últimos dígitos são arredondados.
  • sector é o identity.category do lugar, como Padaria.
  • scrapedAt é quando coletamos o lugar pela última vez.

Quando a exportação é recusada

RespostaO que houve e o que fazer
409 CONFLICTA coleta ainda não encontrou nenhum lugar. Espere os primeiros chegarem e tente de novo.
409 CONFLICTA coleta terminou sem lugares, então não há o que exportar. Tente uma região maior ou outros termos.
409 CONFLICTOs lugares da coleta foram apagados, 30 dias depois que ela começou. As contagens continuam lá. Comece a mesma coleta de novo e exporte a nova.
400 VALIDATION_ERRORA coleta tem mais de 50.000 lugares, o máximo que cabe num xlsx. Exporte em csv.
404 COLLECTION_NOT_FOUNDO id está errado ou é de outra conta.