Die meisten APIs lassen Sie raten, wo Sie bei der Nutzung stehen, bis etwas kaputtgeht. My Geocode geht einen anderen Weg: Jede einzelne Antwort, auf jedem Endpunkt und jedem Kompatibilitäts-Host, enthält einen vollständigen Satz von Kontingent-Headern, die Ihnen genau sagen, wo Sie stehen.
X-Quota-Limit und X-Quota-Used liefern das Grundbild für den aufrufenden Schlüssel oder das Netzwerk. X-Quota-Free-Remaining zeigt, wie viel vom kostenlosen Tageskontingent noch übrig ist, und X-Quota-Network-Used gibt an, wie viel dieses gemeinsamen kostenlosen Kontingents pro Netzwerk bereits von irgendeiner Adresse oder irgendeinem Schlüssel über dieselbe Verbindung verbraucht wurde. X-Credits-Remaining zeigt den Stand des Prepaid-Guthabens für alle, die über die kostenlose Stufe hinaus sind und kein Unlimited-Paket haben. X-Key-IPs-Used und X-Key-IPs-Limit erfassen, von wie vielen verschiedenen Adressen aus ein Schlüssel verwendet wurde, und X-Quota-Reset sagt Ihnen, wann die Tageszähler zurückgesetzt werden.
Der Grund, warum das wichtig ist, ist einfach: Ein Skript, das sein eigenes Kontingent sehen kann, kann sich intelligent danach richten. Es kann langsamer werden, bevor es blockiert wird, einen Entwickler benachrichtigen, wenn das Guthaben knapp wird, oder automatisch von einem kostenlosen zu einem bezahlten Schlüssel wechseln, statt erst zu scheitern und hinterher zu reagieren. Nichts davon erfordert den Aufruf eines separaten Nutzungs-Endpunkts oder einen manuellen Blick ins Dashboard. Die Information kommt mit der Antwort, die Sie ohnehin angefordert haben.
Das gilt unabhängig davon, ob Sie unsere nativen Endpunkte oder einen der siebzehn Kompatibilitäts-Hosts nutzen. Eine Anfrage im Format eines Aufrufs an die Google Maps Platform, die Bing Maps REST Services oder ipstack kommt trotzdem mit unseren Kontingent-Headern zurück, zusätzlich zu dem Antwortinhalt, der dem Format dieses Anbieters entspricht. Ein Anbieterwechsel bedeutet nicht, diese Transparenz zu verlieren, sondern sie an Stellen zu gewinnen, die sie nie hatten.
Jeder Schlüssel erhält ein kostenloses Tageskontingent. Darüber hinaus werden Anfragen vom Prepaid-Guthaben abgebucht oder durch ein Unlimited-Paket abgedeckt. Jede Antwort teilt Ihnen in ihren Headern mit, wo Sie stehen, was bei einem einzelnen Aufruf eine Kleinigkeit ist und über einen geschäftigen Tag voller Traffic hinweg wirklich nützlich.
Teams, die mehr als ein einmaliges Skript bauen, empfehlen wir, diese Header von Anfang an zusammen mit ihren eigenen Anfrageprotokollen zu loggen. Ein stiller Trend, bei dem X-Quota-Free-Remaining schneller sinkt als erwartet, lässt sich in einem Diagramm viel günstiger bemerken als in einem Support-Ticket. Alle Details zu jedem Header und dazu, was ihn auslöst, sind unter /docs/rate-limits/ dokumentiert, zusammen mit allgemeinen Hinweisen zur Authentifizierung unter /docs/authentication/.