Encoder et décoder des adresses Alkax Grid

Alkax Grid v1 attribue à une coordonnée une référence de cellule compacte et déterministe. Chaque cellule mesure nominalement cinq mètres de côté. Une adresse Grid désigne une cellule géographique ; ce n’est ni un lieu Alkax enregistré, ni un identifiant de lieu, ni une preuve de propriété ou de l’existence d’un lieu à cet endroit. Le décodage fonctionne aussi pour les cellules inhabitées.

Le format canonique est CC-XXYY-LLLLL : un espace de noms de pays à deux lettres, quatre caractères de zone et cinq caractères de cellule locale. Le code utilise l’alphabet 23456789CFGHJMPQRVWX. La v1 couvre 55 espaces de noms de pays africains. Ses origines sont immuables ; une évolution des limites peut modifier le pays attribué à une coordonnée encodée, mais ne déplace pas un cadre v1 existant. Les limites sont des données cartographiques de référence, pas des frontières topographiques.

Dans l’application Alkax

Les détails d’un lieu enregistré permettent de copier son adresse Grid, et les textes de partage ainsi que les pages publiques d’adresse partagée l’incluent lorsqu’elle est disponible. La recherche sur la carte accepte une adresse Grid canonique et ouvre le centre de la cellule décodée. Ce résultat désigne la cellule, pas un lieu enregistré ; les filtres de lieux enregistrés ne s’appliquent pas. La carte utilise un point de terminaison interne dédié au décodage ; il ne fait pas partie de l’explorateur public de l’API développeur et ne nécessite pas de clé développeur.

Authentification et quota

Les deux opérations exigent un identifiant développeur côté serveur dans X-Alkax-Key avec la portée places:read. Elles fonctionnent avec des identifiants Sandbox et Production. Gardez le secret sur votre serveur ; ne l’exposez pas dans le code du navigateur. Les requêtes comptent dans le quota mensuel normal de l’API développeur et ses limites de débit ; il n’existe pas de quota Grid distinct. Consultez le guide de la plateforme développeur et le guide d’authentification. Avant d’exécuter l’une des requêtes, définissez ALKAX_KEY avec votre clé Sandbox ou Production :

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

Encoder des coordonnées

Envoyez la latitude et la longitude sous forme de nombres JSON. La latitude doit être comprise entre -90 et 90, et la longitude entre -180 et 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 est un vecteur de référence publié. Sa réponse est :

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

L’encodage résout d’abord la coordonnée dans la géométrie configurée des limites des pays, puis utilise le cadre immuable de ce pays. Une coordonnée hors de la géométrie d’un pays pris en charge ou du cadre v1 correspondant renvoie 422. Si la géométrie des limites ne peut pas être chargée, l’encodage renvoie 503.

Décoder une adresse canonique

Envoyez l’adresse en JSON. Cet appel décode le même vecteur publié et renvoie le centre de sa cellule :

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"}'

Le décodage utilise le registre des cadres v1 figés et ne charge pas la géométrie des pays ni ne vérifie l’existence d’un lieu dans la cellule. Les minuscules et les espaces autour du code sont acceptés et normalisés dans canonicalAddress. Le service accepte une chaîne d’adresse de 32 caractères au maximum avant la validation du format ; la sortie canonique comporte toujours 13 caractères.

Adresses Grid dans les réponses de lieux

Lorsque la coordonnée correspond à une couverture v1, les réponses principales de lecture, de recherche, de création et de mise à jour des lieux incluent un objet gridAddress de premier niveau. Sa valeur est null si la coordonnée ne correspond pas à un cadre pris en charge. Par exemple, une réponse contient :

{
  "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
  }
}

Les réponses compactes GET /api/v1/addresses/{plusCode} et POST /api/v1/addresses/verify possèdent aussi un gridAddress nullable de premier niveau. La réponse du passeport public le place dans geography.gridAddress. Ces codes sont des identifiants distincts : id identifie un lieu enregistré, plusCode son Plus Code existant et gridAddress.canonicalAddress une cellule v1. Une cellule Grid ne garantit pas qu’un lieu Alkax y soit enregistré.

Erreurs et limites

Les erreurs du service utilisent l’objet de réponse standard avec code, message et un tableau errors. Chaque détail de ce tableau comporte les champs code, description et severity. Les erreurs de validation du corps de la requête renvoient plutôt un tableau d’erreurs de validation.

Statut	Cas d’utilisation
400	Des coordonnées manquantes ou hors limites renvoient un tableau d’erreurs de validation. Une adresse vide ou de plus de 32 caractères échoue aussi à la validation de la requête. Une adresse mal formée, un espace de noms non pris en charge ou une valeur inutilisée renvoie AddressGridInvalidRequest dans l’objet d’erreur standard.
422	La coordonnée à encoder est hors de la géométrie d’un pays pris en charge ou du cadre v1 (AddressGridOutsideCoverage)
503	La géométrie des pays est indisponible pour l’encodage (AddressGridGeometryUnavailable)
401	Identifiant développeur absent ou invalide
403	L’identifiant ne possède pas la portée places:read
402	L’abonnement Production est inactif ou ne donne pas accès à Production
429	Le quota de requêtes du projet ou de l’abonnement est épuisé, ou une limite de débit est atteinte

Par exemple, une réponse hors couverture a la forme suivante :

{
  "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"
    }
  ]
}

Seul encode dépend de la géométrie des pays. L’opération decode peut renvoyer 400 pour une entrée invalide, mais ne renvoie pas 422 ni 503 pour une question de couverture géométrique. Les limites des pays sont des données cartographiques de référence, pas des frontières topographiques ; les coordonnées sur les limites des polygones peuvent rester sans correspondance. Consultez la référence API pour les schémas publiés des points de terminaison.