Encode and decode Alkax Grid addresses

Alkax Grid v1 gives a coordinate a compact, deterministic cell reference. Each cell is nominally five metres across. A grid address identifies a location cell; it is not a registered Alkax place, a place ID, proof of ownership, or evidence that a place exists there. Decoding works for uninhabited cells too.

The canonical format is CC-XXYY-LLLLL: a two-letter country namespace, four zone characters and five local-cell characters. The code uses the alphabet 23456789CFGHJMPQRVWX. V1 covers 55 African country namespaces. Its origins are immutable; boundary-data changes can affect which country an encoded coordinate resolves to, but cannot move an existing v1 frame. The country boundaries are cartographic reference data, not survey-grade borders.

In the Alkax app

Saved-place details let you copy the Grid address, and share text and public shared-address pages include it when available. Map search accepts a canonical Grid address and takes you to the decoded cell center. That result represents the cell location, not a registered place; saved-place filters do not apply. The map uses a dedicated first-party endpoint for decoding; it is not part of the public Developer API explorer and does not need a developer key.

Authentication and quota

Both operations require a server-side developer credential in X-Alkax-Key with the places:read scope. They work with Sandbox credentials as well as Production credentials. Keep the secret on your server; do not expose it in browser code. Requests count toward the project's normal Developer API monthly allowance and rate limits; there is no separate grid quota. See the developer platform guide and authentication guide. Before running either request, set ALKAX_KEY to your Sandbox or Production key:

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

Encode coordinates

Send latitude and longitude as JSON numbers. Latitude must be between -90 and 90, and longitude between -180 and 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 is a published reference vector. Its response is:

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

Encoding first resolves the coordinate against configured country-boundary geometry, then uses the immutable frame for that country. A coordinate outside supported country geometry or the corresponding v1 frame returns 422. If boundary geometry cannot be loaded, encoding returns 503.

Decode a canonical address

Send the address in JSON. This call decodes the same published vector and returns its cell center:

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

Decoding uses the frozen v1 frame registry and does not load country geometry or check whether a place exists at the cell. Lowercase characters and surrounding whitespace are accepted and normalized in canonicalAddress. The service accepts an address string up to 32 characters before format validation; canonical output is always 13 characters.

Grid addresses on place responses

Where the coordinate resolves within v1 coverage, core place read, search, create, and update responses include a top-level gridAddress object. It is null when the coordinate cannot be resolved to a supported frame. For example, a response contains:

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

The compact GET /api/v1/addresses/{plusCode} and POST /api/v1/addresses/verify responses also have a nullable top-level gridAddress. The public passport response nests it at geography.gridAddress. These codes are separate identifiers: id identifies a registered place, plusCode identifies its existing Plus Code, and gridAddress.canonicalAddress identifies a v1 cell. A grid cell does not guarantee that an Alkax place is registered there.

Errors and limits

Service errors use the standard response object with code, message and an errors array. A detail in that array has code, description and severity fields. Request-body validation errors return an array of validation failures instead.

Status	When it occurs
400	Missing or out-of-range coordinates return a validation-failure array. An empty or over-32-character address also fails request validation. A malformed address, unsupported namespace, or unused code value returns AddressGridInvalidRequest in the standard error object.
422	Encoding coordinate is outside supported country geometry or the v1 frame (AddressGridOutsideCoverage)
503	Country geometry is unavailable for encoding (AddressGridGeometryUnavailable)
401	Missing or invalid developer credential
403	Credential does not have places:read
402	Production subscription is inactive or does not provide Production access
429	Project or subscription request allowance is exhausted, or a rate limit is reached

For example, an outside-coverage response has this shape:

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

Only encode depends on country geometry. The decode operation can still return 400 for invalid input, but does not return 422 or 503 for geometry coverage. Country boundaries are cartographic reference data rather than survey-grade borders; coordinates on polygon boundaries may be unresolved. See the API reference for the published endpoint schemas.