Monitore o uso da sua chave antes de atingir um limite
Acompanhar seus cabeçalhos de cota ao longo do caminho mostra quando um limite está se aproximando, bem antes de uma requisição ser realmente rejeitada.
Envie sua chave de API de três formas diferentes (e por que isso importa)
Nem toda ferramenta que se comunica com uma API trata a autenticação da mesma forma, e é por isso que a API aceita a chave por mais de um mecanismo, em vez de obrigar tudo a passar por um único nome de cabeçalho.
O cabeçalho X-API-Key
Esta é a opção mais direta, um cabeçalho dedicado que carrega apenas a chave.
GET /v1/forward?q=Baker+Street
X-API-Key: mg_live_examplekey123Authorization: Bearer
Alguns clientes HTTP e gateways de API já vêm configurados para anexar um token bearer a toda requisição enviada, e usar esse mecanismo significa que você não precisa adicionar um segundo cabeçalho, específico da API, ao lado dele.
GET /v1/forward?q=Baker+Street
Authorization: Bearer mg_live_examplekey123Autenticação HTTP Basic
Ferramentas mais antigas, e algumas integrações entre servidores criadas para outros provedores, esperam credenciais via autenticação HTTP Basic. A chave vai como nome de usuário, com a senha em branco.
GET /v1/forward?q=Baker+Street
Authorization: Basic bWdfbGl2ZV9leGFtcGxla2V5MTIzOg==Um parâmetro de consulta, para todo o resto
Quando uma ferramenta não dá nenhum controle sobre os cabeçalhos, como um teste rápido na barra de endereços do navegador ou um cliente que só aceita configuração pela URL, a chave também pode ser enviada como parâmetro de consulta diretamente na requisição.
GET /v1/forward?q=Baker+Street&key=mg_live_examplekey123Por que a escolha importa na prática
Uma chave enviada como parâmetro de consulta acaba em logs de servidor, no histórico do navegador e em cabeçalhos de referência com muito mais facilidade do que uma enviada em um cabeçalho da requisição, então prefira um método baseado em cabeçalho sempre que o código que faz a chamada tiver algum controle sobre isso. Os quatro métodos funcionam de forma idêntica em todos os endpoints e em todos os hosts de compatibilidade, então trocar de um para outro depois, por exemplo ao migrar um script de um teste no navegador para uma integração de backend adequada, não muda nada na forma como a cota ou o crédito são contabilizados para a chave.
Como usar isso nos hosts de compatibilidade
Cada um dos 17 hosts de compatibilidade aceita credenciais no mesmo estilo usado pelo provedor original, então um script escrito para a convenção de autenticação de outro provedor geralmente continua funcionando depois que você o aponta para o host de compatibilidade correspondente da My Geocode, sem reescrever a forma como a chave é enviada. Consulte a página de compatibilidade para ver a lista de hosts e o estilo de credencial que cada um espera.
Um erro que vale a pena evitar
Testar um script com a chave como parâmetro de consulta e deixá-lo assim em produção é um hábito fácil de adquirir, já que o parâmetro de consulta costuma ser o jeito mais rápido de fazer a primeira requisição funcionar. Passe para um método baseado em cabeçalho, X-API-Key ou Authorization, antes que o script chegue perto do tráfego de produção ou seja enviado para um repositório compartilhado, já que uma chave visível em uma URL tem muito mais chance de acabar em um lugar que você não pretendia, como um log de proxy ou um arquivo de histórico do navegador em uma máquina compartilhada.
Nenhuma diferença de custo
Nenhum desses métodos muda a forma como uma requisição é cobrada. Toda requisição feita com a chave continua contando da mesma forma para as suas 2.500 requisições gratuitas por dia e, além disso, para o crédito pré-pago ou um pacote Unlimited.
Escolher o método de autenticação certo é principalmente uma questão de acompanhar o que a ferramenta que faz a chamada já suporta, e não de desempenho ou custo. Os detalhes completos estão na documentação de autenticação.