AFA.codes
Meine Adresse erstellen

API-Dokumentation

Digitale Adressen in Ihrem System – mit einem einzigen Aufruf

Wandeln Sie Koordinaten in AFA-Codes (Encode) und AFA-Codes in Standorte (Decode) um. Fertige Beispiele im Modellgebiet Boa Vista/RR.

Im Playground ausprobieren Kostenloses Konto erstellen

Einführung

Die AFA.codes-API kann zwei Dinge – und jedes davon ist ein eigener Vertrag mit eigenem Schlüssel und eigenem Tarif:

ENCODE

Koordinate → AFA-Code

Senden Sie Breiten- und Längengrad (WGS84) und erhalten Sie den Code des 4 × 4 m großen Quadrats. Einzelpunkt oder Batch.

DECODE

AFA-Code → Standort

Senden Sie einen Code in beliebiger Schreibweise und erhalten Sie die kanonische Schreibweise, den Mittelpunkt und das Polygon der Zelle.

Alle Antworten verwenden denselben JSON-Umschlag: { "success": true, "data": … } oder { "success": false, "error": { "code", "message" } }. Die API liefert niemals personenbezogene Daten – weder CPF noch CNPJ noch Namen: Sie wandelt nur Koordinaten in Codes um.

Basis-URL:

https://app.afa.codes/api

Schnellstart

  1. 1

    Erstellen Sie Ihr Konto als Unternehmen oder Entwickler – das dauert nur wenige Minuten, ganz ohne Vertriebsgespräch.

  2. 2

    Erstellen Sie im Dashboard einen Sandbox-Schlüssel: Er funktioniert im Modellgebiet Boa Vista/RR und verbraucht kein Freikontingent.

  3. 3

    Führen Sie den ersten Aufruf aus:

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

Antwort · 200

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

Sie möchten ohne Schlüssel testen? Nutzen Sie den Playground, der echte Encode- und Decode-Aufrufe mit einem Demo-Schlüssel ausführt.

Authentifizierung

Jeder Aufruf erfordert einen API-Schlüssel im Header X-API-Key. Anonymen Zugriff gibt es nicht: Jeder Schlüssel gehört zu einem Vertrag (ENCODE, DECODE oder Gebiet) Ihres Kontos.

Header

X-API-Key: afa_live_xxxxxxxxxxxxxxxxxxxxxxxx
  • 1 Schlüssel pro Vertrag. Encode und Decode sind unabhängige Verträge – der Schlüssel des einen funktioniert nicht beim anderen.
  • Sandbox vs. Produktion. Sandbox-Schlüssel funktionieren nur im Modellgebiet Boa Vista/RR, mit bis zu 1.000 Anfragen pro Tag, und verbrauchen kein Freikontingent. Produktionsschlüssel funktionieren in ganz Brasilien.
  • Bewahren Sie den Schlüssel auf dem Server auf. Er wird nur ein einziges Mal angezeigt; falls er bekannt wird, widerrufen Sie ihn und erstellen Sie im Dashboard einen neuen.

Kanonische Schreibweise

Der ausgegebene AFA-Code ist immer die Stufe L36: 8 Zeichen, die ein Quadrat von 4 × 4 m (16 m²) bezeichnen. Die API akzeptiert bei der Eingabe Varianten und liefert immer die kanonische Schreibweise.

FormBeispielVerwendung
LesbarR7FTD-HXUDokumente, Adressschilder, Bildschirme (5 + Bindestrich + 3)
APIBR~R7FTDHXUFeld afacode in den Antworten (Länderpräfix, ohne Bindestrich)
KompaktR7FTDHXUAls Eingabe akzeptiert

Groß- und Kleinschreibung sind bei der Eingabe gleichwertig. Das Alphabet verwendet keine Vokale (außer U), um zufällige Wörter zu vermeiden.

Encode

POST

/v1/encode

Einzelpunkt: Senden Sie lat und lng (WGS84). Optionale Felder: ref (Ihre Kennung, wird in der Antwort zurückgegeben) und label. Fügen Sie ?geometry=true hinzu, um das Polygon der Zelle zu erhalten.

Batch · Anfrage

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 · Antwort

{
  "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: bis zu 1.000 Punkte pro Aufruf. Ein Aufruf mit N Punkten zählt als N Anfragen für Freikontingent und Paket.

Decode

GET

/v1/decode/{code}

Akzeptiert R7FTD-HXU, R7FTDHXU oder BR~R7FTDHXU. Liefert die kanonische Schreibweise, den Mittelpunkt und – standardmäßig – das Polygon der Zelle (abschaltbar mit ?geometry=false).

cURL · Decode

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

Antwort · 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": [...] }. Zählt ebenfalls als N Anfragen.

GET

/v1/usage

Monatsverbrauch Ihres Kontos (Freikontingent, Paket, genutzter Anteil) – nützlich zur Überwachung der Integration.

Fehler

Fehler kommen mit success: false, einem stabilen code (verwenden Sie ihn in Ihrem Code) und einer message auf Portugiesisch.

Beispiel · 429

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Pacote do mês esgotado. Faça upgrade de plano para continuar."
  }
}
CodeHTTPWann er auftritt
API_KEY_REQUIRED401Header X-API-Key fehlt.
API_KEY_INVALID401Schlüssel existiert nicht oder wurde widerrufen.
CONTRACT_NOT_ACTIVE402Der Schlüssel hat keinen aktiven Vertrag (z. B. Zahlung ausstehend).
CONTRACT_SUSPENDED402Vertrag wegen Zahlungsverzugs ausgesetzt.
WRONG_CONTRACT_TYPE403ENCODE-Schlüssel für DECODE verwendet (oder umgekehrt) – es sind unabhängige Verträge.
OUTSIDE_SANDBOX403Sandbox-Schlüssel außerhalb des Modellgebiets Boa Vista/RR verwendet.
OUTSIDE_TERRITORY403Punkt außerhalb des vertraglich vereinbarten Gebiets (Gebietspaket).
VALIDATION_ERROR400Ungültiger Body (z. B. Breitengrad außerhalb von -90..90, Batch über dem Maximum).
INVALID_AFACODE400Der Code ist in keiner akzeptierten Schreibweise ein gültiger AFA-Code.
OUT_OF_COVERAGE422Koordinate außerhalb des Abdeckungsbereichs (außerhalb Brasiliens oder auf dem Meer).
UNKNOWN_AFACODE422Code korrekt aufgebaut, aber außerhalb des brasilianischen Rasters.
QUOTA_EXCEEDED429Freikontingent und Paket des Monats ausgeschöpft. Führen Sie ein Upgrade durch oder warten Sie bis zum Monatswechsel.
RATE_LIMITED429Technisches Limit von 50 Anfragen pro Sekunde und Schlüssel.
SANDBOX_LIMIT429Tageslimit der Sandbox (1.000 Anfragen) erreicht.

Limits und Abrechnung

3.000 Decode

kostenlos pro Monat und Konto

25 Encode

kostenlos pro Monat und Konto

  • Das Freikontingent gilt pro Konto (CNPJ/CPF), nicht pro Schlüssel: Mehr Schlüssel vervielfachen das Freikontingent nicht. Es erneuert sich jeden Monat und verfällt am Monatsende.
  • Nach dem Freikontingent wird der Verbrauch auf das vertraglich vereinbarte Paket angerechnet (feste Monatsgebühr je Stufe – Mehrverbrauch wird nicht berechnet).
  • Abgerechnet wird pro Anfrage: Ein Batch-Aufruf mit N Elementen zählt als N.
  • Bei 90 % des Pakets senden wir eine Warn-E-Mail. Ist es ausgeschöpft, werden die Aufrufe bis zum Monatswechsel oder bis zu einem Tarif-Upgrade gesperrt (QUOTA_EXCEEDED).
  • Technisches Limit: 50 Anfragen pro Sekunde und Schlüssel.

Preise

Feste Monatsgebühr je Volumenstufe. Encode und Decode werden separat gebucht.

ENCODE

StufeEncode/Monat (bis)MonatsgebührR$/1.000
N1 50kostenlos—
N2 1.000500,00 R$500
N3 5.0002.000,00 R$400
N4 15.0005.500,00 R$367
N5 35.00011.000,00 R$314
N6 65.00018.000,00 R$277
N7 100.00025.000,00 R$250

Über 100.000/Monat: auf Anfrage (AFACODES Projetos).

DECODE

StufeDecode/Monat (bis)MonatsgebührR$/1.000
N1 500kostenlos—
N2 5.000225,00 R$45
N3 25.0001.000,00 R$40
N4 75.0002.625,00 R$35
N5 150.0004.500,00 R$30
N6 300.0008.100,00 R$27
N7 500.00012.500,00 R$25

Über 500.000/Monat: auf Anfrage (AFACODES Projetos).

DECODE for Startups

Jahrestarif

1.500 Abfragen pro Monat für den Einstieg.

1.800,00 R$/Jahr

Alle Lösungen ansehen

Jetzt kostenlos starten

Das monatliche Freikontingent ist im Konto enthalten. Testen Sie in der Sandbox und wechseln Sie in die Produktion, wann Sie möchten.

Konto erstellenPlayground