Kontingente, Guthaben und Limits

Jeder Schlüssel erhält ein kostenloses Tageskontingent. Darüber hinaus werden Anfragen vom Prepaid-Guthaben abgebucht oder sind durch ein Unlimited-Paket abgedeckt. Jede Antwort zeigt Ihnen in ihren Headern, wo Sie stehen.

Das Tageskontingent

Das Kontingent mit Schlüssel gilt pro Schlüssel, nicht pro Konto: Drei Schlüssel bedeuten dreimal 2.500 kostenlose Anfragen. Das Kontingent ohne Schlüssel gilt pro Adresse, und Adressen im selben Netzwerk teilen es sich. Ein Netzwerk und die daraus verwendeten Schlüssel greifen auf ein gemeinsames Kontingent zu: Anfragen ohne Schlüssel verringern, was ein aus demselben Netzwerk verwendeter Schlüssel an diesem Tag erhält, und umgekehrt, sodass die kostenlosen 2.500 nicht zweimal vom selben Ort genutzt werden können. Guthaben gilt pro Konto und wird von dem Schlüssel verbraucht, der sein Kontingent überschreitet. Der Tag ist der UTC-Kalendertag; X-Quota-Reset enthält die genaue Unix-Zeit des nächsten Zurücksetzens.

Was als Anfrage zählt

• Jeder erfolgreiche Aufruf (200) eines beliebigen Endpunkts zählt als eine Anfrage, unabhängig davon, ob etwas gefunden wurde.
• Jedes Element in einem Massenaufruf zählt als eine Anfrage: jede Adresse in einem IP-Batch, jeder Punkt in einem Höhen- oder Zeitzonenaufruf mit mehreren Punkten, jeder Eintrag an den Batch-Endpunkten der Drop-in-Hosts. So zählen es auch die ursprünglichen Anbieter. Ein Batch, der größer ist als das verbleibende Kontingent, wird vor jeglicher Verarbeitung vollständig abgelehnt, mit dem eigenen Limitfehler des Anbieters, statt teilweise beantwortet zu werden. Jeder Host nimmt so viele Elemente pro Aufruf an wie sein ursprünglicher Anbieter (100 für ip-api und MapQuest, 50 für ipstack, 512 für Google Elevation, 1.000 für ipinfo, Mapbox und Geoapify, 1.024 für Bing und Open-Elevation, 10.000 für Geocodio und den asynchronen Batch von TomTom; 100 an den nativen Endpunkten). Das Abrufen eines gespeicherten asynchronen Ergebnisses wird nicht gezählt.
• Aufrufe, die mit 400, 401, 402, 403 oder 404 abgelehnt werden, zählen nicht und kosten nichts.
• Aufrufe, die mit 500 oder 503 fehlschlagen, zählen nicht und kosten nichts.
• Kartenkacheln, Style-JSON und das Laden von Bibliotheken der JavaScript-Drop-ins zählen nicht.

IP-Plätze

Ein Schlüssel funktioniert gleichzeitig von zwei IP-Adressen aus (drei bei einem Unlimited-Schlüssel). Jede Adresse hält ihren Platz 24 Stunden ab ihrer ersten Anfrage und gibt ihn dann frei. Eine Anfrage von einer weiteren Adresse, während alle Plätze belegt sind, erhält 403 key_ip_limit mit dem Zeitpunkt, an dem der nächste Platz frei wird. Details und Beispiele stehen auf der Seite zur Authentifizierung.

Lastspitzen

Derzeit gibt es kein festes Limit an Anfragen pro Sekunde, mit oder ohne Schlüssel. Datenverkehr, der wie eine außer Kontrolle geratene Schleife oder ein Angriff aussieht, kann gebremst werden, und wir sagen Ihnen Bescheid, wenn das bei einem Ihrer Schlüssel passiert. Bei großen Aufträgen verwenden Sie die Batch-Formen (ips, locations) statt Tausender Einzelaufrufe.

Die Header lesen

x-quota-limit: 2500          # free per day for this key; -1 on an Unlimited key
x-quota-used: 2431           # counted today on this key, including this request
x-quota-free-remaining: 69   # free requests left today on this key
x-credits-remaining: 148200  # requests the account's credit still covers
x-key-ips-used: 1            # IP slots currently held on this key
x-key-ips-limit: 2           # slots on this key
x-quota-reset: 1789948800    # Unix time of the next 00:00 UTC
x-request-id: 2726386e38428697

Umgang mit 402 und 403

{ "status": "error", "error": { "code": "no_credits", "message": "The free allowance of 2500 requests for today is used and the account balance (€0.0000, 0 requests) does not cover this request. Add credit at https://www.mygeocode.com/dashboard or wait for the reset at 00:00 UTC." } }

Wiederholen Sie nicht in einer Schleife; die Antwort bleibt dieselbe, bis Guthaben aufgeladen oder der Tag zurückgesetzt wird. Lesen Sie X-Quota-Reset und warten Sie entweder, brechen Sie den Vorgang ab und informieren Sie den Nutzer, oder laden Sie Guthaben auf. Das Dashboard schickt Ihnen eine E-Mail, wenn das Guthaben knapp wird.

{ "status": "error", "error": { "code": "key_ip_limit", "message": "This key is already in use from 2 IP addresses in the last 24 hours (limit 2). The next slot frees at 2026-09-21 23:06 UTC. Use another key or an additional Unlimited package for more addresses." } }

Das bedeutet, dass ein Rechner, der derzeit keinen Platz des Schlüssels belegt, versucht hat, ihn zu verwenden. Meist ist das ein neuer Server oder ein erneutes Deployment mit einer neuen Adresse; geben Sie diesem Rechner einen eigenen Schlüssel.

Anfragen reduzieren

Sie dürfen Ergebnisse unbegrenzt zwischenspeichern, also tun Sie es. Adressen bewegen sich nicht; dieselbe Geokodierung liefert morgen dieselbe Antwort. IP-Blöcke ändern sich langsam; ein Tag ist eine sichere Cache-Dauer. Zeitzonenregeln für einen Punkt ändern sich selten und der IANA-Name praktisch nie. Bei der Autovervollständigung verzögern Sie die Eingabe (Debounce) um etwa 150 ms und senden nichts mehr, sobald der Nutzer einen Vorschlag gewählt hat.