Codificar e descodificar endereços Alkax Grid

O Alkax Grid v1 atribui a uma coordenada uma referência de célula compacta e determinística. Cada célula tem nominalmente cinco metros de lado. Um endereço Grid identifica uma célula de localização; não é um local Alkax registado, um ID de local, uma prova de propriedade ou evidência de que existe um local nesse ponto. A descodificação também funciona para células desabitadas.

O formato canónico é CC-XXYY-LLLLL: um espaço de nomes de país com duas letras, quatro carateres de zona e cinco carateres de célula local. O código utiliza o alfabeto 23456789CFGHJMPQRVWX. A v1 abrange 55 espaços de nomes de países africanos. As origens são imutáveis; alterações aos dados de fronteiras podem afetar o país atribuído a uma coordenada codificada, mas não deslocam um quadro v1 existente. As fronteiras são dados cartográficos de referência, não limites cadastrais.

Na aplicação Alkax

Os detalhes de um local guardado permitem copiar o endereço Grid, e as mensagens de partilha e as páginas públicas de endereço partilhado incluem-no quando está disponível. A pesquisa no mapa aceita um endereço Grid canónico e leva-o ao centro da célula descodificada. Esse resultado representa a localização da célula, não um local registado; os filtros de locais guardados não se aplicam. O mapa utiliza um endpoint próprio da aplicação para descodificar; não faz parte do explorador público da API de programador e não requer uma chave de programador.

Autenticação e quota

Ambas as operações exigem uma credencial de programador no servidor no cabeçalho X-Alkax-Key com o âmbito places:read. Funcionam com credenciais Sandbox e Production. Mantenha o segredo no servidor; não o exponha no código do navegador. Os pedidos contam para a quota mensal normal da API de programador e para os respetivos limites de frequência; não existe uma quota Grid separada. Consulte o guia da plataforma de programador e o guia de autenticação. Antes de executar qualquer pedido, defina ALKAX_KEY com a sua chave Sandbox ou Production:

export ALKAX_KEY="ak_test_<key-id>.<secret>"

Codificar coordenadas

Envie a latitude e a longitude como números JSON. A latitude tem de estar entre -90 e 90, e a longitude entre -180 e 180:

curl "https://api.alkax.io/api/v1/addresses/grid/encode" \
  --request POST \
  --header "X-Alkax-Key: $ALKAX_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{"latitude":-1.2921,"longitude":36.8219}'

Nairobi é um vetor de referência publicado. A resposta é:

{
  "version": 1,
  "canonicalAddress": "KE-3R43-XMWRR",
  "countryCode": "KE",
  "centerLatitude": -1.2920930818547325,
  "centerLongitude": 36.82189788797723,
  "cellSizeMetres": 5
}

A codificação resolve primeiro a coordenada através da geometria configurada das fronteiras dos países e, em seguida, utiliza o quadro imutável desse país. Uma coordenada fora da geometria de um país suportado ou do quadro v1 correspondente devolve 422. Se a geometria das fronteiras não puder ser carregada, a codificação devolve 503.

Descodificar um endereço canónico

Envie o endereço em JSON. Esta chamada descodifica o mesmo vetor publicado e devolve o centro da célula:

curl "https://api.alkax.io/api/v1/addresses/grid/decode" \
  --request POST \
  --header "X-Alkax-Key: $ALKAX_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{"address":"KE-3R43-XMWRR"}'

A descodificação utiliza o registo fixo de quadros v1 e não carrega a geometria dos países nem verifica se existe um local na célula. São aceites letras minúsculas e espaços em redor, normalizados em canonicalAddress. O serviço aceita uma cadeia de endereço até 32 carateres antes da validação do formato; a saída canónica tem sempre 13 carateres.

Endereços Grid nas respostas de locais

Quando a coordenada resolve dentro da cobertura v1, as respostas principais de leitura, pesquisa, criação e atualização de locais incluem um objeto gridAddress de nível superior. O valor é null quando não é possível associar a coordenada a um quadro suportado. Por exemplo, uma resposta contém:

{
  "id": "<registered-place-uuid>",
  "plusCode": "<registered-place-plus-code>",
  "gridAddress": {
    "version": 1,
    "canonicalAddress": "KE-3R43-XMWRR",
    "countryCode": "KE",
    "centerLatitude": -1.2920930818547325,
    "centerLongitude": 36.82189788797723,
    "cellSizeMetres": 5
  }
}

As respostas compactas GET /api/v1/addresses/{plusCode} e POST /api/v1/addresses/verify também têm um gridAddress anulável de nível superior. A resposta do passaporte público coloca-o em geography.gridAddress. Estes códigos são identificadores distintos: id identifica um local registado, plusCode identifica o respetivo Plus Code existente e gridAddress.canonicalAddress identifica uma célula v1. Uma célula Grid não garante que exista um local Alkax registado nesse ponto.

Erros e limites

Os erros do serviço utilizam o objeto de resposta padrão com code, message e uma matriz errors. Cada detalhe nessa matriz tem os campos code, description e severity. Os erros de validação do corpo do pedido devolvem uma matriz de falhas de validação.

Estado	Quando ocorre
400	Coordenadas em falta ou fora dos limites devolvem uma matriz de falhas de validação. Um endereço vazio ou com mais de 32 carateres também falha a validação do pedido. Um endereço malformado, espaço de nomes não suportado ou valor não utilizado devolve AddressGridInvalidRequest no objeto de erro padrão.
422	A coordenada de codificação está fora da geometria de um país suportado ou do quadro v1 (AddressGridOutsideCoverage)
503	A geometria dos países está indisponível para codificação (AddressGridGeometryUnavailable)
401	Credencial de programador em falta ou inválida
403	A credencial não tem o âmbito places:read
402	A subscrição Production está inativa ou não permite acesso Production
429	A quota de pedidos do projeto ou da subscrição foi esgotada, ou foi atingido um limite de frequência

Por exemplo, uma resposta fora da cobertura tem este formato:

{
  "code": "AddressGridOutsideCoverage",
  "message": "The coordinate is outside Alkax Grid v1 coverage.",
  "errors": [
    {
      "code": "AddressGridOutsideCoverage",
      "description": "The coordinate is outside Alkax Grid v1 coverage.",
      "severity": "Error"
    }
  ]
}

Só encode depende da geometria dos países. A operação decode pode devolver 400 para uma entrada inválida, mas não devolve 422 nem 503 por cobertura geométrica. As fronteiras dos países são dados cartográficos de referência, não limites cadastrais; as coordenadas sobre os limites dos polígonos podem não ser resolvidas. Consulte a referência da API para ver os esquemas publicados dos pontos finais.