Exportações

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.

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.

• 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 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.

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:

• 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.