AFA.codes
Generate my address

API documentation

Digital addresses in your system, in a single call

Convert coordinates into AFA Codes (encode) and AFA Codes into locations (decode). Ready-to-run examples in the Boa Vista/RR sample area.

Try it in the playground Create a free account

Introduction

The AFA.codes API does two things — and each one is a separate contract, with its own key and its own plan:

ENCODE

Coordinates → AFA Code

Send a latitude and longitude (WGS84) and get the code of the 4 × 4 m square. Accepts a single point or a batch.

DECODE

AFA Code → location

Send a code in any accepted format and get the canonical format, the center and the polygon of the cell.

Every response uses the same JSON envelope: { "success": true, "data": … } or { "success": false, "error": { "code", "message" } }. The API never returns personal data — no CPF, no CNPJ, no name: it only converts coordinates into codes and back.

Base URL:

https://app.afa.codes/api

Quickstart

  1. 1

    Create your account as a company or developer — it takes just a few minutes and there's no need to talk to sales.

  2. 2

    In the dashboard, generate a sandbox key: it works in the Boa Vista/RR sample area and doesn't count against your free allowance.

  3. 3

    Make your first call:

cURL · encode

curl -X POST https://app.afa.codes/api/v1/encode \
  -H "X-API-Key: $AFA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "lat": 2.8235, "lng": -60.6758 }'

Response · 200

{
  "success": true,
  "data": {
    "afacode": "BR~QYWL9P6U",
    "human": "QYWL9-P6U",
    "level": "L36",
    "center": { "lat": 2.8234874, "lng": -60.675808 }
  }
}

Want to try it without a key? Use the playground, which runs real encode and decode calls with a demo key.

Authentication

Every call requires an API key in the X-API-Key header. There is no anonymous access: each key belongs to a contract (ENCODE, DECODE or Territory) on your account.

Header

X-API-Key: afa_live_xxxxxxxxxxxxxxxxxxxxxxxx
  • 1 key per contract. Encode and decode are separate contracts — a key for one doesn't work for the other.
  • Sandbox vs. production. Sandbox keys only work in the Boa Vista/RR sample area, with up to 1,000 requests per day, and don't count against your free allowance. Production keys work across Brazil.
  • Keep the key on your server. It is shown only once; if it leaks, revoke it and generate a new one in the dashboard.

Canonical format

The exposed AFA Code is always level L36: 8 characters that identify a 4 × 4 m square (16 m²). The API accepts variations as input and always returns the canonical format.

FormatExampleUsage
HumanR7FTD-HXUDocuments, address plates, screens (5 + hyphen + 3)
APIBR~R7FTDHXUafacode field in responses (country prefix, no hyphen)
CompactR7FTDHXUAccepted as input

Input is case-insensitive. The alphabet has no vowels (except U) to avoid spelling out words by accident.

Encode

POST

/v1/encode

Single point: send lat and lng (WGS84). Optional fields: ref (your own identifier, echoed in the response) and label. Add ?geometry=true to get the cell polygon.

Batch · request

curl -X POST "https://app.afa.codes/api/v1/encode?geometry=false" \
  -H "X-API-Key: $AFA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
      { "lat": 2.8235, "lng": -60.6758, "ref": "pedido-1001" },
      { "lat": 2.8199, "lng": -60.6714, "ref": "pedido-1002" }
    ]
  }'

Batch · response

{
  "success": true,
  "data": {
    "count": 2,
    "results": [
      { "ref": "pedido-1001", "afacode": "BR~QYWL9P6U", "human": "QYWL9-P6U", "level": "L36",
        "center": { "lat": 2.8234874, "lng": -60.675808 } },
      { "ref": "pedido-1002", "afacode": "BR~QYWLDJ6W", "human": "QYWLD-J6W", "level": "L36",
        "center": { "lat": 2.8199166, "lng": -60.6713986 } }
    ]
  }
}
Batch: up to 1,000 points per call. A call with N points counts as N requests against the free allowance and the package.

Decode

GET

/v1/decode/{code}

Accepts R7FTD-HXU, R7FTDHXU or BR~R7FTDHXU. Returns the canonical format, the center and — by default — the cell polygon (turn it off with ?geometry=false).

cURL · decode

curl https://app.afa.codes/api/v1/decode/QYWL9-P6U \
  -H "X-API-Key: $AFA_API_KEY"

Response · 200

{
  "success": true,
  "data": {
    "afacode": "BR~QYWL9P6U",
    "human": "QYWL9-P6U",
    "level": "L36",
    "center": { "lat": 2.8234874, "lng": -60.675808 },
    "cell": {
      "type": "Polygon",
      "coordinates": [[[-60.675826, 2.823469], [-60.675791, 2.823469],
                       [-60.675790, 2.823505], [-60.675825, 2.823506],
                       [-60.675826, 2.823469]]]
    }
  }
}
POST

/v1/decode

Batch: { "codes": ["QYWL9-P6U", "BR~QYWLDJ6W"] } → { "count", "results": [...] }. Also counts as N requests.

GET

/v1/usage

Your account's usage for the month (free allowance, package, percentage used) — useful for monitoring your integration.

Errors

Errors come with success: false, a stable code (use it in your code) and a message in Portuguese.

Example · 429

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Pacote do mês esgotado. Faça upgrade de plano para continuar."
  }
}
CodeHTTPWhen it happens
API_KEY_REQUIRED401Missing X-API-Key header.
API_KEY_INVALID401Key does not exist or has been revoked.
CONTRACT_NOT_ACTIVE402The key has no active contract (e.g. awaiting payment).
CONTRACT_SUSPENDED402Contract suspended for non-payment.
WRONG_CONTRACT_TYPE403ENCODE key used for DECODE (or vice versa) — they are separate contracts.
OUTSIDE_SANDBOX403Sandbox key used outside the Boa Vista/RR sample area.
OUTSIDE_TERRITORY403Point outside the contracted territory (Territory package).
VALIDATION_ERROR400Invalid request body (e.g. latitude outside -90..90, batch above the maximum).
INVALID_AFACODE400The code is not a valid AFA Code in any accepted format.
OUT_OF_COVERAGE422Coordinates outside coverage (outside Brazil or at sea).
UNKNOWN_AFACODE422Well-formed code, but outside the Brazilian grid.
QUOTA_EXCEEDED429Free allowance and monthly package used up. Upgrade or wait for the next month.
RATE_LIMITED429Technical limit of 50 requests per second per key.
SANDBOX_LIMIT429Daily sandbox limit (1,000 requests) reached.

Limits and billing

3,000 decode

free per month, per account

25 encode

free per month, per account

  • The free allowance belongs to the account (CNPJ/CPF), not the key: more keys don't multiply it. It renews every month and doesn't roll over.
  • Once the free allowance is used up, usage counts against your contracted package (fixed monthly fee per tier — there are no overage charges).
  • Billing is per request: a batch call with N items counts as N.
  • When you reach 90% of your package, we send you an alert email. Once it's used up, calls are blocked (QUOTA_EXCEEDED) until the next month or a plan upgrade.
  • Technical limit: 50 requests per second per key.

Pricing

Fixed monthly fee per volume tier. Encode and decode are purchased separately.

ENCODE

LevelEncode/month (up to)Monthly feeR$/1k
N1 50free—
N2 1,000R$500.00500
N3 5,000R$2,000.00400
N4 15,000R$5,500.00367
N5 35,000R$11,000.00314
N6 65,000R$18,000.00277
N7 100,000R$25,000.00250

Over 100,000/month: on request (AFACODES Projetos).

DECODE

LevelDecode/month (up to)Monthly feeR$/1k
N1 500free—
N2 5,000R$225.0045
N3 25,000R$1,000.0040
N4 75,000R$2,625.0035
N5 150,000R$4,500.0030
N6 300,000R$8,100.0027
N7 500,000R$12,500.0025

Over 500,000/month: on request (AFACODES Projetos).

DECODE for Startups

annual plan

1,500 requests per month for those just getting started.

R$1,800.00/year

See all solutions

Get started now, for free

The free monthly allowance comes with your account. Test in the sandbox and go live whenever you're ready.

Create accountPlayground