互換性

このAPIを使うために、このAPIを覚える必要はありません。他の17のジオコーディングAPIとIP検索APIについて、そのプロバイダーのリクエスト形式を受け付け、そのプロバイダーのレスポンス形式で応答し、背後で当社のデータを使うホストを用意しています。これらのプロバイダーが提供するJavaScript地図ライブラリについても同様です。移行はホスト名を変えるだけです。

仕組み

各互換ホストは、1つのプロバイダーの公開HTTPインターフェースを完全に実装しています。同じパス、同じクエリパラメータ、同じJSONフィールド名・入れ子構造・型、同じステータスの語彙、同じエラー形式です。値は当社のものです。クライアントコード、解析コード、エラー処理は変わりません。

1. ホストを変更します。 maps.googleapis.comはgapi.mygeocode.comに、dev.virtualearth.netはbing.mygeocode.comに、というように変わります。すべての組み合わせは下の表にあります。
2. キーを入れ替えるか、削除します。以前のキーが使っていたパラメータ（key、apiKey、access_token、tokenなど）にMy Geocodeのキーを入れてください。どのアドレスもキーなしで1日あたり2,500件の無料リクエストを利用でき、どのキーにも独自に2,500件が付くため、移行とテストに費用はかかりません。
3. 比較します。実際のリクエストのサンプルを両方のホストに送ってください。データが異なるため座標はわずかに違いますが、フィールド名は同じです。

$ curl "https://maps.googleapis.com/maps/api/geocode/json?address=10+Downing+St+London&key=GOOGLE_KEY"

$ curl "https://gapi.mygeocode.com/maps/api/geocode/json?address=10+Downing+St+London&key=MYGEOCODE_KEY"

すべての互換ホスト

すべてのホストはapi.mygeocode.comと同じインフラ、同じデータ、同じ無料枠、同じ料金で動作します。プロバイダーをクリックすると、エンドポイントの一覧、レスポンスのサンプル、既知の相違点が表示されます。

JavaScript地図ライブラリ

プロバイダーの変更が最も大変なのはブラウザです。地図、ジオコーダーのウィジェット、課金が絡み合っているからです。以下のライブラリでは、ライブラリ自体を当社のホストから読み込み（MapLibre、Mapbox GL、Leafletの場合は設定で当社のホストを指定し）、公開APIはそのまま維持されます。google.maps.Map、Microsoft.Maps.Map、H.Mapなどです。タイル、ジオコーディング、オートコンプリート、標高は当社から提供されます。地図の読み込みとタイルは無料で、ジオコーディングの呼び出しは通常どおり数えられます。

JavaScript互換ライブラリのページに、変更前後のコード例、ライブラリごとに含まれるものと含まれないものの一覧、タイルとスタイルのURLがあります。

キーの置き場所

各ホストは、元のプロバイダーが想定する場所とX-API-Keyヘッダーの両方でキーを受け付けます。キーは任意で、アドレスごとに1日あたり2,500件のリクエストはキーなしで利用できます。無料のキーは1分ほどで取得でき、クレジット、パッケージ、利用履歴が加わります。従量課金キーは連続する24時間あたり2つのIPアドレスから、Unlimitedキーは3つから利用できます。より多くのアドレスで使うには、キーやパッケージを追加してください（認証をご覧ください）。

互換ホストでの割り当てとエラー

1日の割り当ては他のすべての場所と同じで、api.mygeocode.comとすべての互換ホストを合算し、キーごと（キーが送信されない場合はアドレスごと）に数えられます。1日あたり2,500件が無料で、それを超えるとクレジットまたはUnlimitedキーが使われます。X-Quota-*とX-Key-IPs-*ヘッダーはすべてのホストで送信されるため、本文の形式にかかわらず、ヘッダーから実際の状態を読み取れます。本文では、上限はプロバイダーと同じ方法で報告されます。

一致する点と一致しない点

移行チェックリスト

1. コードと設定からプロバイダーのホスト名を検索します。サーバーのコード、モバイルアプリ、CDNのルール、キャッシュされた設定など、複数の場所にあることがよくあります。
2. 上の表にある互換ホストに変更します。パスはそのままにします。
3. キーをMy Geocodeのキーに置き換えます。サーバーごとに1つ、多くても2台で1つのキーを使ってください。従量課金キーは連続する24時間あたり2つのIPアドレス、Unlimitedキーは3つまで受け付けます。
4. 既存のテストスイートを実行します。変更なしで通るはずです。依存しているフィールドがない場合は、ホストのページで既知の不足点を確認し、当社にお知らせください。
5. 実際のリクエストを数百件両方のホストに送り直し、座標と表示しているフィールドを比較します。互換ホストがprecisionを公開している場合（location_type、accuracy、resultTypeなど）は、それも確認してください。
6. 1日ほどX-Quota-Usedを観察して、プランの規模を決めます。1日あたり約19,000件未満ならクレジット、それを超えるならUnlimitedキーです。
7. 以前の課金を解約します。

プロバイダーのSDK

ほとんどの公式クライアントライブラリはカスタムのベースURLを受け付けるため、互換ホストでも動作します。Google Maps Servicesのクライアント（Python用のgooglemaps、@googlemaps/google-maps-services-js）、MapboxのSDK（originオプション）、HEREのRESTクライアント、ipinfoのライブラリ、geopyなどのNominatimラッパー（domain=）です。表にあるホストを指定し、プロバイダーのキーがあった場所にMy Geocodeのキーを渡してください。

一覧にないプロバイダー

プロバイダーの形式がドキュメント化されていれば、ホストの追加は数日の作業です。ここにないサービスをお使いの場合は、サービス名と、1日あたりのおおよそのリクエスト数をお知らせください。最近追加したものはすべてユーザーからの要望によるものです。