Authentifizierung

Die ersten 2.500 Anfragen pro Tag von einer Adresse brauchen keinen Schlüssel. Ein Schlüssel ist für alles darüber hinaus: Er bestimmt, auf wessen Guthaben oder Paket eine Anfrage angerechnet wird und welche Rechner ihn nutzen dürfen, und er liefert Ihnen einen Nutzungsverlauf. Schlüssel sind kostenlos und in einer Minute erstellt.

Ohne Schlüssel

Senden Sie die Anfrage ganz ohne Zugangsdaten, und sie wird beantwortet. Jede Adresse erhält auf diese Weise 2.500 Anfragen pro Tag, gezählt ab 00:00 UTC über alle Endpunkte und alle Drop-in-Hosts hinweg, mit denselben Daten und denselben Antworten wie ein zahlendes Konto. Darüber hinaus antwortet die API bis zum Zurücksetzen mit 429 quota_exceeded und einem Header Retry-After; es wird nichts berechnet und nichts in eine Warteschlange gestellt.

Zwei Dinge sollten Sie wissen. Adressen, die zum selben Netzwerk gehören, teilen sich ein Kontingent, sodass ein belebtes Büro, ein Campus oder eine Cloud-Region es schneller aufbrauchen kann als ein einzelner Rechner. Und ein Netzwerk und die daraus verwendeten Schlüssel greifen auf dasselbe Kontingent zu: Anfragen ohne Schlüssel verringern, was ein aus diesem Netzwerk verwendeter Schlüssel heute erhält, und kostenlose Anfragen mit diesem Schlüssel verringern, was das Netzwerk ohne Schlüssel erhält. Eine Registrierung bringt daher Guthaben, Pakete und einen Verlauf, aber keine zweiten kostenlosen 2.500 vom selben Ort.

Einen Schlüssel erhalten

Registrieren Sie sich unter www.mygeocode.com/signup mit Ihrem Namen, einer E-Mail-Adresse und einem Passwort. Ihr erster Schlüssel wird einmalig sofort angezeigt; kopieren Sie ihn, denn gespeichert wird nur ein Hash. Unter API-Schlüssel können Sie beliebig viele weitere Schlüssel erstellen, jedem eine Bezeichnung geben (einer pro Server oder pro Anwendung ist eine gute Gewohnheit) und jeden davon jederzeit widerrufen.

Jeder Schlüssel hat 2.500 kostenlose Anfragen pro Tag, gezählt ab 00:00 UTC über alle Endpunkte und alle Drop-in-Hosts hinweg. Darüber hinaus werden Anfragen mit je 0,0001 € vom Prepaid-Guthaben des Kontos abgebucht, es sei denn, der Schlüssel gehört zu einem Unlimited-Paket.

Den Schlüssel senden

Jede dieser Varianten funktioniert auf jedem Host. Bevorzugen Sie den Header: Query-Strings landen in Server-Logs, Browserverläufen und Proxys.

$ curl -H "X-API-Key: mg_7f3c2a19e04b...d1" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

$ curl -H "Authorization: Bearer mg_7f3c2a19e04b...d1" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

$ curl "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12&key=mg_7f3c2a19e04b...d1"

$ curl -u "mg_7f3c2a19e04b...d1:" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

Auf den Drop-in-Hosts kommt der Schlüssel außerdem überall dorthin, wo der Schlüssel des ursprünglichen Anbieters stand: key für Google, Bing, Geocode.Farm, OpenCage, LocationIQ, TomTom und MapQuest; apiKey für HERE und Geoapify; access_token für Mapbox; api_key für Geocodio; access_key für PositionStack und ipstack; token für ipinfo. Clients für Nominatim und Open-Elevation fügen key= oder einen Header hinzu, da diese beiden Dienste keinen eigenen Schlüssel haben.

Neben dem Query-Parameter werden auf jedem Host vier Arten der Übermittlung von Zugangsdaten akzeptiert, sodass eine Client-Bibliothek, die sich auf die Art des Anbieters authentifiziert, keine Änderung braucht: der Header X-API-Key, Authorization: Bearer, HTTP-Basic-Authentifizierung mit dem Schlüssel als Benutzername (was curl -u KEY: sendet und was die ipinfo-Beispiele verwenden) und der Header X-Goog-Api-Key, den die Clients von Google senden. Ein Schlüssel im Formular-Body wird ebenfalls gelesen, für die Endpunkte, an die per POST gesendet wird. Hostname und Schlüssel zu ändern ist die gesamte Migration.

Zwei Arten von Schlüsseln

IP-Plätze

Ein Schlüssel darf gleichzeitig nur von einer begrenzten Zahl von IP-Adressen verwendet werden: von zwei bei einem nutzungsbasierten Schlüssel, von drei bei einem Unlimited-Schlüssel. Die Regel ist rollierend, pro Adresse:

• Wenn eine Adresse den Schlüssel zum ersten Mal verwendet, belegt sie einen Platz und hält ihn 24 Stunden ab dieser ersten Anfrage.
• Wenn diese 24 Stunden abgelaufen sind, wird der Platz von selbst frei, unabhängig davon, was die anderen Adressen tun. Kommt dieselbe Adresse später wieder, belegt sie einfach erneut einen Platz.
• Eine Anfrage von einer neuen Adresse, während alle Plätze belegt sind, wird mit 403 und dem Code key_ip_limit abgelehnt. Die Meldung sagt, wann der nächste Platz frei wird. Abgelehnte Anfragen werden nicht gezählt.

Wenn also zwei Server einen Schlüssel erstmals um 02:00 verwendet haben und ein dritter um 04:00, werden zwei Plätze am nächsten Tag um 02:00 frei und der dritte um 04:00. Das Dashboard zeigt, welche Adressen die Plätze eines Schlüssels belegen und wann jeder frei wird. Sie brauchen mehr Rechner? Erstellen Sie weitere nutzungsbasierte Schlüssel oder fügen Sie weitere Unlimited-Pakete hinzu; jedes Paket bringt seinen eigenen Schlüssel mit.

Das Limit gibt es, weil Schlüssel nach außen gelangen. Damit ist ein Schlüssel, der in einem öffentlichen Repository landet, für den Finder kaum etwas wert, und da das Guthaben im Voraus bezahlt wird, kann niemand mehr ausgeben als das Guthaben, das Sie aufgeladen haben.

Schlüssel und Browser

Legen Sie keinen Schlüssel in JavaScript oder in einer mobilen App ab. Jeder kann ihn aus der Seite auslesen, und jeder Besucher ist eine neue IP-Adresse, sodass die Plätze des Schlüssels nach dem zweiten oder dritten Besucher aufgebraucht sind. Rufen Sie die API von Ihrem eigenen Server auf und bewahren Sie den Schlüssel dort auf. Die JavaScript-Karten-Drop-ins laden Kacheln und Bibliotheken ohne Schlüssel; nur ihre Geokodierungsaufrufe müssen über Ihren Server laufen.

Widerrufen und rotieren

Widerrufen Sie einen Schlüssel im Dashboard, und er funktioniert innerhalb einer Minute nicht mehr. Erstellen Sie zuerst den neuen Schlüssel, setzen Sie ihn ein und widerrufen Sie dann den alten; in der Zwischenzeit funktionieren beide. Schlüssel laufen nie von selbst ab.

Ablehnungen

Keine davon wird auf das Kontingent angerechnet oder kostet Guthaben. Auf den Drop-in-Hosts werden sie in der Struktur des ursprünglichen Anbieters gemeldet; siehe Kompatibilität.