Nach der Registrierung im Kundenbereich unter API-Keys einen Key anlegen. Der Klartext-Wert wird genau einmal angezeigt – danach ist nur noch das Präfix sichtbar.
Jeder Key hat Scopes: geo:read für die Abfrage-Endpunkte,
geo:bulk für Batch-Aufrufe, mcp:use für den MCP-Server.
Der Key wird als Bearer-Token übergeben:
curl -H "Authorization: Bearer $GEO_API_KEY" \
"https://geodata.bitfertig.de/api/v1/geocode?q=Neue%20Promenade%205,%2010178%20Berlin&limit=3"Antwort (gekürzt):
{
"query": "Neue Promenade 5, 10178 Berlin",
"count": 1,
"results": [
{
"id": "address:365710:5",
"type": "address",
"name": "Neue Promenade 5",
"location": { "lat": 52.52297, "lon": 13.40171 },
"address": {
"street": "Neue Promenade",
"house_number": "5",
"postal_code": "10178",
"city": "Berlin",
"country": "DE"
}
}
]
}
Das Feld type nennt die Genauigkeit des Treffers:
address ist die exakte Hausnummer, street die
Straßenmitte und city die Ortsmitte. Wer eine
Hausnummer mitschickt, bekommt die Originalkoordinate aus
OpenStreetMap.
Jede Antwort enthält Header zum aktuellen Stand:
| Header | Bedeutung |
|---|---|
X-Quota-Limit | Monatskontingent des Tarifs |
X-Quota-Remaining | verbleibende Einheiten |
X-RateLimit-Plan | erlaubte Anfragen pro Minute |
Der aktuelle Stand ist außerdem über GET /api/v1/me und im
Kundenbereich abrufbar.
| Status | Fehlercode | Bedeutung |
|---|---|---|
| 401 | unauthenticated | Key fehlt, ist widerrufen oder abgelaufen |
| 402 | subscription_required | Kein aktives Abo – Tarif buchen oder Zahlung aktualisieren |
| 403 | – | Dem Key fehlt der benötigte Scope |
| 422 | – | Ungültige Parameter, Details unter errors |
| 429 | rate_limit_exceeded | Zu viele Anfragen pro Minute – erneut versuchen |
| 429 | quota_exceeded | Monatskontingent erschöpft – Tarif wechseln oder warten |
Client-Fehler (4xx) verbrauchen kein Kontingent.