Para scripts próprios
Chaves pessoais
Uma chave pessoal permite que o código próprio consulte a conta Mapit. É só de leitura, a não ser que também seja autorizada a gerir ligações, e pertence ao cliente: pode ser apagada quando se quiser.
Beta, gratuita por agora. As chaves pessoais fazem parte da beta da API da Mapit: podem mudar e não têm garantia de disponibilidade. Ver as condições da beta.
Criar uma chave
- Abrir login.mapit.me/connections e iniciar sessão com o email e a palavra-passe Mapit.
- Em Chaves pessoais, dar à chave um nome reconhecível, como «Script da garagem».
- Marcar a localização, o histórico de trajetos e a gestão de ligações só se o código precisar deles.
- Voltar a introduzir a palavra-passe e criar a chave. Uma chave continua a funcionar mesmo que a palavra-passe seja alterada depois, por isso a Mapit pede-a mais uma vez.
- Copiar a chave. Começa por
mapit_e só é mostrada uma vez.
A chave deve ser tratada como uma palavra-passe: mantê-la fora do código partilhado e das capturas de ecrã. Se for divulgada, apagá-la na mesma página e criar outra.
Usar a chave
Enviá-la como token bearer:
export MAPIT_KEY=mapit_...
curl -H "Authorization: Bearer $MAPIT_KEY" https://api.mapit.me/v1/vehicles
curl -H "Authorization: Bearer $MAPIT_KEY" https://api.mapit.me/v1/status Em Python:
import os, requests
r = requests.get("https://api.mapit.me/v1/status",
headers={"Authorization": f"Bearer {os.environ['MAPIT_KEY']}"},
timeout=20)
r.raise_for_status()
for v in r.json()["vehicles"]:
s = v["state"] or {}
print(v["vehicleId"], s.get("latitude"), s.get("longitude"), s.get("lastLocationAt")) O que uma chave pode fazer
| Permissão | Sempre | Se marcada |
|---|---|---|
| Conta, veículos, subscrição | Sim | |
| Última localização comunicada e estado do dispositivo | Localização | |
| Histórico de trajetos e estatísticas de condução | Histórico de trajetos | |
| Ver e desligar as aplicações ligadas e as chaves | Gerir ligações |
Um pedido fora das permissões da chave responde 403. Para as alterar, criar uma chave nova.
Consultar sem descarregar os mesmos dados
Cada resposta traz um ETag. Devolvê-lo em If-None-Match; 304 sem corpo significa que nada mudou. Continua a contar para os 30 pedidos por minuto.
# The first answer carries the tag
curl -sD- -o status.json -H "Authorization: Bearer $MAPIT_KEY" https://api.mapit.me/v1/status
# Send it back: 304 and no body until a vehicle reports something new
curl -sD- -o status.json -H "Authorization: Bearer $MAPIT_KEY" -H 'If-None-Match: W/"..."' https://api.mapit.me/v1/status Gerir ligações
Uma chave criada com Gerir ligações pode ver todas as aplicações ligadas à conta (Home Assistant, Claude, ChatGPT…) e todas as chaves, e desligar qualquer uma. Só as chaves pessoais podem ter esta permissão; nenhuma aplicação a pode pedir. A página de ligações assinala estas chaves com «pode gerir ligações».
curl -H "Authorization: Bearer $MAPIT_KEY" https://api.mapit.me/v1/me/connections
curl -X DELETE -H "Authorization: Bearer $MAPIT_KEY" https://api.mapit.me/v1/me/connections/con_... Uma chave com esta permissão pode desligar as aplicações. Deve ser entregue apenas a código de confiança e, se as ligações começarem a desaparecer, convém apagar as chaves assinaladas com «pode gerir ligações». O name de uma aplicação é o que ela própria escolheu, a não ser que builtIn seja true.
Limites
Os valores atuais estão em Limites. Hoje:
- Uma chave dura um ano. A página de ligações mostra quando expira cada uma.
- Até 10 chaves por conta.
- 30 pedidos por minuto por chave; acima disso, a API responde
429comRetry-Afterem segundos.
