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.
Introduction
The AFA.codes API does two things — and each one is a separate contract, with its own key and its own plan:
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.
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/apiQuickstart
- 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
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
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.
| Format | Example | Usage |
|---|---|---|
| Human | R7FTD-HXU | Documents, address plates, screens (5 + hyphen + 3) |
| API | BR~R7FTDHXU | afacode field in responses (country prefix, no hyphen) |
| Compact | R7FTDHXU | Accepted as input |
Input is case-insensitive. The alphabet has no vowels (except U) to avoid spelling out words by accident.
Encode
/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 } }
]
}
}Decode
/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]]]
}
}
}/v1/decode
Batch: { "codes": ["QYWL9-P6U", "BR~QYWLDJ6W"] } → { "count", "results": [...] }. Also counts as N requests.
/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."
}
}| Code | HTTP | When it happens |
|---|---|---|
API_KEY_REQUIRED | 401 | Missing X-API-Key header. |
API_KEY_INVALID | 401 | Key does not exist or has been revoked. |
CONTRACT_NOT_ACTIVE | 402 | The key has no active contract (e.g. awaiting payment). |
CONTRACT_SUSPENDED | 402 | Contract suspended for non-payment. |
WRONG_CONTRACT_TYPE | 403 | ENCODE key used for DECODE (or vice versa) — they are separate contracts. |
OUTSIDE_SANDBOX | 403 | Sandbox key used outside the Boa Vista/RR sample area. |
OUTSIDE_TERRITORY | 403 | Point outside the contracted territory (Territory package). |
VALIDATION_ERROR | 400 | Invalid request body (e.g. latitude outside -90..90, batch above the maximum). |
INVALID_AFACODE | 400 | The code is not a valid AFA Code in any accepted format. |
OUT_OF_COVERAGE | 422 | Coordinates outside coverage (outside Brazil or at sea). |
UNKNOWN_AFACODE | 422 | Well-formed code, but outside the Brazilian grid. |
QUOTA_EXCEEDED | 429 | Free allowance and monthly package used up. Upgrade or wait for the next month. |
RATE_LIMITED | 429 | Technical limit of 50 requests per second per key. |
SANDBOX_LIMIT | 429 | Daily 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
| Level | Encode/month (up to) | Monthly fee | R$/1k |
|---|---|---|---|
| N1 | 50 | free | — |
| N2 | 1,000 | R$500.00 | 500 |
| N3 | 5,000 | R$2,000.00 | 400 |
| N4 | 15,000 | R$5,500.00 | 367 |
| N5 | 35,000 | R$11,000.00 | 314 |
| N6 | 65,000 | R$18,000.00 | 277 |
| N7 | 100,000 | R$25,000.00 | 250 |
Over 100,000/month: on request (AFACODES Projetos). | |||
DECODE
| Level | Decode/month (up to) | Monthly fee | R$/1k |
|---|---|---|---|
| N1 | 500 | free | — |
| N2 | 5,000 | R$225.00 | 45 |
| N3 | 25,000 | R$1,000.00 | 40 |
| N4 | 75,000 | R$2,625.00 | 35 |
| N5 | 150,000 | R$4,500.00 | 30 |
| N6 | 300,000 | R$8,100.00 | 27 |
| N7 | 500,000 | R$12,500.00 | 25 |
Over 500,000/month: on request (AFACODES Projetos). | |||
DECODE for Startups
annual plan1,500 requests per month for those just getting started.
R$1,800.00/year
Get started now, for free
The free monthly allowance comes with your account. Test in the sandbox and go live whenever you're ready.
