ドキュメント

すべてのリクエストは、クエリパラメータを付けてhttps://api.mygeocode.com/v1/に送るGETリクエストで、JSONで応答が返ります。このページでは、すべてのエンドポイントに共通する部分を説明します。各エンドポイントのパラメータとフィールドは、エンドポイントごとのページで説明しています。

最初のリクエスト

1つのアドレスからの1日あたり最初の2,500件のリクエストには、キーは不要です。どのマシンからでも実行できます。

$ 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 }
    }
  ]
}

このリクエストは、あなたのアドレスが今日利用できる2,500件の無料リクエストのうち1件として数えられました。キーを使った場合はキーの分として数えられ、ヘッダーにはクレジットとIPスロットの数値も加わります。レスポンスヘッダーで現在の状況がわかります。

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

他のプロバイダーから移行しますか？

このページの残りは読む必要がないかもしれません。お使いのコードがすでにGoogle Maps、Bing Maps、HERE、Mapbox、Geocode.Farm、Nominatim、OpenCage、LocationIQ、Geoapify、TomTom、MapQuest、Geocodio、PositionStack、ip-api、ipinfo、ipstack、Open-Elevationのいずれかと通信している場合、そのプロバイダーのリクエスト形式とレスポンス形式をそのまま扱い、背後で当社のデータを使うホストを用意しています。ホスト名を変更し、以前のキーがあった場所に新しいキーを入れれば、解析コードはそのまま使えます。Google Maps JavaScript API、Bing Maps V8、HERE Maps for JavaScript、MapQuest.js、そしてMapLibre、Mapbox GL、Leafletのジオコーダープラグインについても同様です。

• Google Maps
• Bing Maps
• HERE
• Mapbox
• Geocode.Farm
• Nominatim
• OpenCage
• LocationIQ
• Geoapify
• TomTom
• MapQuest
• Geocodio
• PositionStack
• ip-api
• ipinfo
• ipstack
• Open-Elevation
• JavaScript地図ライブラリ

互換ホストの仕組み：全ホストの一覧、キーの対応、エラーの対応、移行チェックリスト。

ベースURLとエンドポイント

HTTPSのみで提供しています。キーが誤って平文で送信されることがないよう、通常のHTTPリクエストはリダイレクトせず400で拒否します。HTTP/2とHTTP/3に対応しています。クライアントがgzipまたはbrを受け付ける場合、レスポンスは圧縮されます。

レスポンスエンベロープ

すべてのレスポンスはJSONオブジェクトで、statusはokまたはerrorです。

• okの場合はペイロードが続きます。複数の一致を返す可能性のあるエンドポイントではresults（配列）、逆ジオコーディングではresult（オブジェクトまたはnull）、IP検索とタイムゾーン検索ではフラットなフィールドです。
• errorの場合はerrorオブジェクトがあり、code文字列、messageの文、および該当する場合は原因となったparamが含まれます。HTTPステータスもこれに一致します。エラーをご覧ください。

クエリが正当でも何も一致しない場合は、okとともに空のresults配列、またはnullのresultが返ります。これはエラーではなく、1件のリクエストとして数えられます。

すべてのエンドポイントで使えるパラメータ

パラメータ名は大文字と小文字を区別し、すべて小文字です。未知のパラメータは無視され、空のパラメータは指定なしとして扱われるため、HTMLフォームで任意フィールドを空欄のまま送信できます。座標は10進数の度で、latは-90から90、lonは-180から180です。テキストはUTF-8で、URLエンコードしてください。

認証の概要

キーは任意です。キーがなくても、すべてのアドレスで1日あたり2,500件の無料リクエストを利用できます。キーはX-API-Keyヘッダー、Authorization: Bearerトークン、またはkeyパラメータとして送信します。キーは無料で、アカウントの作成に必要なのは名前、メールアドレス、パスワードだけです。各キーには独自に1日あたり2,500件の無料リクエストがあり、それを超えるとリクエストはアカウントのプリペイドクレジットから1件あたり€0.0001で支払われます。Unlimitedパッケージ（月額€50）に属するキーでは無料です。キーなしのリクエストと、同じネットワークからのキー付きリクエストは、1日の割り当てを共有します。従量課金キーは連続する24時間あたり2つのIPアドレスから、Unlimitedキーは3つのIPアドレスから利用できます。詳しいルールは認証のページにあります。

割り当てヘッダー

ブラウザからの呼び出し

すべてのエンドポイントでCORSが有効で、割り当てヘッダーも公開されていますが、ページのソースに含めたキーは誰でも見ることができ、数人の訪問者でIPスロットを使い切ってしまいます。呼び出しはサーバーから行ってください。キーとブラウザをご覧ください。

バージョニング

パスの接頭辞/v1/がバージョンです。同じバージョン内ではフィールドやパラメータを追加することはあっても、削除や名前の変更は行わず、既存フィールドの意味を変えることもありません。互換性を壊す変更が必要になった場合は/v2/で行い、/v1/は告知から少なくとも6か月間は引き続き動作します。追加はブログのニュースセクションで告知します。

JSONパーサーは未知のフィールドを無視するようにしてください。前方互換性のための要件はそれだけです。