認証

1つのアドレスからの1日あたり最初の2,500件のリクエストには、キーは不要です。キーはそれを超える部分のためのものです。リクエストがどのクレジットやパッケージから支払われるか、どのマシンがそのキーを使えるかを決め、利用履歴も提供します。キーは無料で、1分ほどで取得できます。

キーなしの場合

認証情報を一切付けずにリクエストを送っても応答が返ります。この方法で、すべてのアドレスが1日あたり2,500件のリクエストを利用できます。件数は00:00 UTCから、すべてのエンドポイントとすべての互換ホストを合算して数えられ、有料アカウントと同じデータ、同じ応答が得られます。それを超えると、APIはリセットまでRetry-Afterヘッダー付きで429 quota_exceededを返します。料金は発生せず、リクエストがキューに入ることもありません。

知っておくべき点が2つあります。同じネットワークに属するアドレスは1つの割り当てを共有するため、利用の多いオフィス、キャンパス、1つのクラウドリージョンなどでは、1台のマシンより早く使い切ることがあります。また、ネットワークとそこから使われるキーは同じ割り当てを消費します。キーなしのリクエストは、そのネットワークから使われるキーが今日利用できる分を減らし、そのキーでの無料リクエストは、そのネットワークがキーなしで利用できる分を減らします。したがって、登録によって得られるのはクレジット、パッケージ、履歴であり、同じ場所からさらに2,500件の無料枠が得られるわけではありません。

キーの取得

www.mygeocode.com/signupで、名前、メールアドレス、パスワードを入力して新規登録してください。最初のキーはその場で一度だけ表示されます。保存されるのはハッシュだけなので、必ずコピーしてください。APIキーの画面で追加のキーをいくつでも作成でき、それぞれにラベルを付けられます（サーバーごと、またはアプリケーションごとに1つ作るのがよい習慣です）。どのキーもいつでも無効化できます。

各キーには1日あたり2,500件の無料リクエストがあり、00:00 UTCから、すべてのエンドポイントとすべての互換ホストを合算して数えられます。それを超えると、キーがUnlimitedパッケージに属していない限り、リクエストはアカウントのプリペイドクレジットから1件あたり€0.0001で支払われます。

キーの送信

以下のどの方法もすべてのホストで使えます。クエリ文字列はサーバーログ、ブラウザの履歴、プロキシに残るため、ヘッダーを推奨します。

$ 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"

互換ホストでは、元のプロバイダーでキーを置いていた場所にもキーを置けます。Google、Bing、Geocode.Farm、OpenCage、LocationIQ、TomTom、MapQuestではkey、HEREとGeoapifyではapiKey、Mapboxではaccess_token、Geocodioではapi_key、PositionStackとipstackではaccess_key、ipinfoではtokenです。NominatimとOpen-Elevationにはもともとキーがないため、これらのクライアントではkey=またはヘッダーを追加します。

クエリパラメータ以外にも、4つの認証情報の送信方法をすべてのホストで受け付けるため、プロバイダーの方式で認証するクライアントライブラリも変更は不要です。X-API-Keyヘッダー、Authorization: Bearer、キーをユーザー名とするHTTP Basic認証（curl -u KEY:が送信するもので、ipinfoの例でも使われています）、そしてGoogleのクライアントが送信するX-Goog-Api-Keyヘッダーです。POSTで送信するエンドポイントでは、フォーム本文内のキーも読み取ります。ホスト名とキーを変えるだけで移行は完了です。

2種類のキー

	従量課金キー	Unlimitedキー
取得方法	ダッシュボードで無料で作成	Unlimitedパッケージ（月額€50）ごとに付属
無料リクエスト	1日あたり2,500件	すべて
無料枠を超えた分	アカウントのクレジットから1件あたり€0.0001。残高がなくなると`402`	なし
IPスロット（連続する24時間）	2	3
パッケージが失効した場合		キーは従量課金キーとして引き続き使えます

IPスロット

1つのキーを同時に使えるIPアドレスの数には上限があります。従量課金キーは2つ、Unlimitedキーは3つです。ルールはアドレスごとに期間が順次更新される方式です。

あるアドレスが初めてキーを使うとスロットを1つ占有し、その最初のリクエストから24時間保持します。
その24時間が経過すると、他のアドレスの状況にかかわらずスロットは自動的に解放されます。同じアドレスが後で再び使う場合は、改めてスロットを占有するだけです。
すべてのスロットが占有されているときに新しいアドレスからリクエストがあると、403とコードkey_ip_limitで拒否されます。メッセージには次のスロットが解放される時刻が示されます。拒否されたリクエストは数えられません。

たとえば、2台のサーバーが02:00に、3台目が04:00に初めてキーを使った場合、翌日の02:00に2つのスロットが、04:00に3つ目が解放されます。ダッシュボードでは、どのアドレスがキーのスロットを占有しているか、それぞれいつ解放されるかを確認できます。もっと多くのマシンで使いたい場合は、従量課金キーを追加で作成するか、Unlimitedパッケージを追加してください。パッケージごとに独自のキーが付属します。

この上限があるのは、キーが漏洩するものだからです。上限があれば、公開リポジトリに流出したキーは見つけた人にとってほとんど価値がありません。また、クレジットはプリペイドなので、誰もあなたがチャージした残高以上に使うことはできません。

キーとブラウザ

キーをJavaScriptやモバイルアプリに含めないでください。誰でもページからキーを読み取れますし、訪問者ごとに新しいIPアドレスになるため、2人目か3人目の訪問者でキーのスロットがなくなります。APIは自分のサーバーから呼び出し、キーはそこに保管してください。JavaScript地図の互換ライブラリはキーなしでタイルとライブラリを読み込みます。自分のサーバーを経由する必要があるのは、ジオコーディングの呼び出しだけです。

無効化とローテーション

ダッシュボードでキーを無効化すると、1分以内に使えなくなります。先に新しいキーを作成してデプロイし、その後で古いキーを無効化してください。その間は両方のキーが使えます。キーが自動的に期限切れになることはありません。

拒否

HTTP	`code`	意味
401	`missing_key`	キーが送信されておらず、このサーバーではキーなしのアクセスが無効になっています（既定では有効です）。
429	`quota_exceeded`	このアドレスは、キーなしでの1日の無料枠を使い切りました。`Retry-After`でリセットまでの時間がわかります。
401	`invalid_key`	キーが存在しません。
401	`key_revoked`	キーは無効化されています。
402	`no_credits`	1日の無料枠を使い切り、アカウントの残高もありません。
403	`key_ip_limit`	キーのIPスロットがすべて他のアドレスに占有されています。
403	`account_suspended`	アカウントが停止されています。サポートにお問い合わせください。

これらはいずれも割り当てに数えられず、クレジットも消費しません。互換ホストでは元のプロバイダーの形式で返されます。互換性をご覧ください。