Substituto compatível (drop-in) do TomTom Search

Os endpoints Geocode, Reverse Geocode e Fuzzy Search da TomTom respondem em tomtom.mygeocode.com com a mesma estrutura de summary e results, incluindo o campo freeformAddress que a maioria das integrações exibe.

Troque um nome de host

Host original	`api.tomtom.com`
Use no lugar	`tomtom.mygeocode.com`
Parâmetro da chave	`key` (opcional: qualquer endereço recebe 2.500 requisições por dia sem chave; coloque aqui sua chave do My Geocode para crédito, pacotes e histórico de uso)

Antes

curl "https://api.tomtom.com/search/2/geocode/Avenida%20Paulista%201578%20S%C3%A3o%20Paulo.json?key=YOUR_TOMTOM_KEY"

Depois

curl "https://tomtom.mygeocode.com/search/2/geocode/Avenida%20Paulista%201578%20S%C3%A3o%20Paulo.json?key=YOUR_MYGEOCODE_KEY"

Por que as pessoas migram

O plano gratuito da TomTom é de 2.500 transações por dia, o mesmo que o nosso, mas lá uma transação pode custar vários créditos. Aqui toda chamada é uma requisição, e o uso pago tem uma opção de valor fixo.

A mesma cota gratuita, com ou sem chave. As requisições para tomtom.mygeocode.com contam para as mesmas 2.500 requisições gratuitas por dia que o seu endereço, ou a sua chave, recebe nos nossos próprios endpoints. Acima disso, crédito pré-pago a € 0,0001 por requisição, ou € 50 por mês por uma chave Unlimited. Para se cadastrar, basta um endereço de e-mail.

Ver preços Obtenha uma chave grátis

Endpoints

Caminho em tomtom.mygeocode.com	O que faz	Baseado em
`/search/2/geocode/{query}.json`	Geocodificação	Geocodificação direta
`/search/2/structuredGeocode.json?countryCode=...&streetName=...`	Geocodificação estruturada	Geocodificação direta
`/search/2/reverseGeocode/{lat},{lon}.json`	Geocodificação reversa	Geocodificação reversa
`/search/2/search/{query}.json?typeahead=true`	Busca aproximada com typeahead	Preenchimento automático de endereços

Exemplo de resposta

Isto é o que a requisição acima retorna. Nomes de campo, aninhamento e tipos seguem a TomTom. Só os dados por trás deles são nossos.

Resposta de tomtom.mygeocode.com

{
  "summary": {
    "query": "avenida paulista 1578 sao paulo",
    "queryType": "NON_NEAR",
    "queryTime": 21,
    "numResults": 1,
    "offset": 0,
    "totalResults": 1,
    "fuzzyLevel": 1
  },
  "results": [
    {
      "type": "Point Address",
      "id": "mg.br.addr.7d1a55f2",
      "score": 11.98,
      "address": {
        "streetNumber": "1578",
        "streetName": "Avenida Paulista",
        "municipalitySubdivision": "Bela Vista",
        "municipality": "São Paulo",
        "countrySecondarySubdivision": "São Paulo",
        "countrySubdivision": "São Paulo",
        "countrySubdivisionCode": "SP",
        "postalCode": "01310-200",
        "countryCode": "BR",
        "country": "Brasil",
        "countryCodeISO3": "BRA",
        "freeformAddress": "Avenida Paulista 1578, Bela Vista, São Paulo, SP 01310-200",
        "localName": "São Paulo"
      },
      "position": { "lat": -23.561414, "lon": -46.655881 },
      "viewport": {
        "topLeftPoint": { "lat": -23.560514, "lon": -46.656881 },
        "btmRightPoint": { "lat": -23.562314, "lon": -46.654881 }
      }
    }
  ]
}

Detalhes e diferenças

Nenhuma chave é necessária para as primeiras 2.500 requisições por dia. Para usar uma chave do My Geocode, coloque-a onde ficava a sua chave da TomTom: o parâmetro de consulta key. O cabeçalho X-API-Key, Authorization: Bearer e a autenticação HTTP Basic (a chave como nome de usuário) também funcionam em todos os hosts, então bibliotecas cliente que se autenticam do próprio jeito continuam funcionando sem mudanças.

A geocodificação em texto livre, estruturada e reversa são todas roteadas, além do endpoint de busca.
As respostas mantêm o formato summary e results da TomTom.
O Batch Search funciona dos dois jeitos. POST /search/2/batch/sync.json responde até 100 batchItems de uma vez no formato da TomTom (statusCode e response por item, summary). POST /search/2/batch.json aceita até 10.000, responde 202 com um cabeçalho Location, e o resultado é buscado ali. Cada item do lote conta como uma requisição, da mesma forma que a TomTom conta; um lote maior do que o que resta da cota é recusado por inteiro com o 429 da TomTom, e buscar um resultado armazenado não conta nada.

Se o seu cliente depende de um campo ou comportamento que não está listado aqui, avise-nos. Lacunas de compatibilidade são corrigidas rapidamente porque costumam ser pequenas.

Outros hosts compatíveis

Como funcionam os hosts compatíveis, a visão geral e os substitutos para bibliotecas JavaScript.