Dokumentation

Alles ist eine GET-Anfrage an https://api.mygeocode.com/v1/ mit Query-Parametern, beantwortet mit JSON. Diese Seite behandelt die Teile, die alle Endpunkte gemeinsam haben. Die Seiten der einzelnen Endpunkte beschreiben deren Parameter und Felder.

Ihre erste Anfrage

Für die ersten 2.500 Anfragen pro Tag von einer Adresse ist kein Schlüssel nötig. Von jedem Rechner aus:

$ curl "https://api.mygeocode.com/v1/forward?q=Brandenburg+Gate,+Berlin&limit=1"

{
  "status": "ok",
  "query": "Brandenburg Gate, Berlin",
  "results": [
    {
      "formatted": "Brandenburger Tor, Pariser Platz, 10117 Berlin, Germany",
      "lat": 52.516275,
      "lon": 13.377704,
      "type": "poi",
      "precision": "house",
      "confidence": 0.99,
      "components": {
        "name": "Brandenburger Tor",
        "road": "Pariser Platz",
        "suburb": "Mitte",
        "city": "Berlin",
        "state": "Berlin",
        "postcode": "10117",
        "country": "Germany",
        "country_code": "de"
      },
      "bounds": { "north": 52.516441, "south": 52.516107, "east": 13.377862, "west": 13.377538 }
    }
  ]
}

Diese Anfrage zählte als 1 von den 2.500 kostenlosen Anfragen, die Ihre Adresse heute erhält. Mit einem Schlüssel würde sie stattdessen auf den Schlüssel angerechnet, und die Header würden zusätzlich Ihr Guthaben und Ihre IP-Plätze anzeigen. Die Antwort-Header zeigen Ihnen, wo Sie stehen:

HTTP/2 200
content-type: application/json; charset=utf-8
x-quota-limit: 2500
x-quota-used: 1
x-quota-free-remaining: 2499
x-quota-reset: 1756339200
x-request-id: 2726386e38428697

Sie kommen von einem anderen Anbieter?

Den Rest dieser Seite brauchen Sie vielleicht nicht. Wenn Ihr Code bereits mit Google Maps, Bing Maps, HERE, Mapbox, Geocode.Farm, Nominatim, OpenCage, LocationIQ, Geoapify, TomTom, MapQuest, Geocodio, PositionStack, ip-api, ipinfo, ipstack oder Open-Elevation spricht, betreiben wir einen Host, der das Anfrage- und Antwortformat dieses Anbieters spricht, mit unseren Daten dahinter. Ändern Sie den Hostnamen, setzen Sie Ihren Schlüssel dort ein, wo der alte stand, und behalten Sie Ihren Parsing-Code. Dasselbe gilt für die Google Maps JavaScript API, Bing Maps V8, HERE Maps for JavaScript, MapQuest.js sowie die Geocoder-Plugins für MapLibre, Mapbox GL und Leaflet.

• Google Maps
• Bing Maps
• HERE
• Mapbox
• Geocode.Farm
• Nominatim
• OpenCage
• LocationIQ
• Geoapify
• TomTom
• MapQuest
• Geocodio
• PositionStack
• ip-api
• ipinfo
• ipstack
• Open-Elevation
• JavaScript-Kartenbibliotheken

So funktionieren die Drop-in-Hosts: die vollständige Host-Übersicht, Schlüssel-Zuordnung, Fehler-Zuordnung und eine Checkliste für die Migration.

Basis-URL und Endpunkte

Es wird nur HTTPS bedient. Einfache HTTP-Anfragen werden mit 400 abgelehnt statt umgeleitet, damit ein Schlüssel nie versehentlich im Klartext gesendet wird. HTTP/2 und HTTP/3 werden unterstützt. Antworten werden komprimiert, wenn der Client gzip oder br akzeptiert.

Die Antwort-Hülle

Jede Antwort ist ein JSON-Objekt mit einem status von ok oder error.

• Bei ok folgen die Nutzdaten: results (ein Array) für Endpunkte, die mehrere Treffer liefern können, result (ein Objekt oder null) für die Reverse-Geokodierung und flache Felder für IP- und Zeitzonenabfragen.
• Bei error gibt es ein Objekt error mit einem String code, einem Satz message und, falls relevant, dem param, der den Fehler verursacht hat. Der HTTP-Status stimmt damit überein. Siehe Fehler.

Eine gültige Abfrage ohne Treffer ist ok mit einem leeren Array results oder einem result mit dem Wert null. Das ist kein Fehler und zählt als Anfrage.

Parameter, die jeder Endpunkt akzeptiert

Parameternamen unterscheiden Groß- und Kleinschreibung und werden kleingeschrieben. Unbekannte Parameter werden ignoriert, und leere Parameter gelten als nicht vorhanden, sodass ein HTML-Formular optionale Felder leer absenden kann. Koordinaten sind Dezimalgrad; lat von -90 bis 90 und lon von -180 bis 180. Text ist UTF-8 und sollte URL-kodiert sein.

Authentifizierung in einem Absatz

Ein Schlüssel ist optional: Jede Adresse erhält ohne Schlüssel 2.500 kostenlose Anfragen pro Tag. Ein Schlüssel wird als Header X-API-Key, als Token Authorization: Bearer oder als Parameter key gesendet; Schlüssel sind kostenlos, und für ein Konto brauchen Sie nur Ihren Namen, eine E-Mail-Adresse und ein Passwort. Jeder Schlüssel hat eigene 2.500 kostenlose Anfragen pro Tag; darüber hinaus nutzen Anfragen das Prepaid-Guthaben des Kontos zu je 0,0001 € oder sind kostenlos mit einem Schlüssel, der zu einem Unlimited-Paket (50 € pro Monat) gehört. Anfragen ohne Schlüssel und Anfragen mit einem Schlüssel aus demselben Netzwerk teilen sich ein tägliches Kontingent. Ein nutzungsbasierter Schlüssel funktioniert von zwei IP-Adressen innerhalb von rollierenden 24 Stunden, ein Unlimited-Schlüssel von drei. Die vollständigen Regeln stehen auf der Seite zur Authentifizierung.

Kontingent-Header

Aufrufe aus dem Browser

CORS ist auf jedem Endpunkt aktiviert und die Kontingent-Header sind freigegeben, aber ein Schlüssel im Seitenquelltext ist öffentlich und hätte seine IP-Plätze nach ein paar Besuchern aufgebraucht. Führen Sie die Aufrufe von Ihrem Server aus; siehe Schlüssel und Browser.

Versionierung

Das Pfadpräfix /v1/ ist die Version. Innerhalb einer Version fügen wir Felder und Parameter hinzu, entfernen oder benennen sie aber nie um und ändern nie die Bedeutung eines bestehenden Felds. Falls wir jemals etwas Inkompatibles ändern müssen, kommt es in /v2/, und /v1/ funktioniert nach der Ankündigung mindestens sechs Monate weiter. Neuerungen werden in der Rubrik News des Blogs angekündigt.

Ihr JSON-Parser sollte Felder ignorieren, die er nicht kennt. Das ist die einzige Anforderung an die Vorwärtskompatibilität.