上限に達する前にキーの使用状況を監視する
割り当てヘッダーを随時確認しておけば、リクエストが実際に拒否されるよりずっと前に、上限が近づいていることが分かります。
検索結果がない場合のフォールバックを用意する
正常に返されたものの中に有用な結果がないリクエストは、扱いを誤りやすいものです。HTTPレベルでは失敗に見えず、ただ期待していた答えが含まれていないだけだからです。
空の結果とはどのようなものか
あいまいすぎるもの、あるいはまったく架空のものを対象にしたジオコーディング検索は、エラーコードではなく、空のresults配列とともにステータス200を返します。
GET /v1/forward?q=xyzzy nonexistent place&limit=1{
"status": "ok",
"query": "xyzzy nonexistent place",
"results": []
}未割り当ての範囲またはプライベート範囲のアドレスに対するIP検索は、エラーではなくfound: falseを返し、それでも埋められるフィールドがあればあわせて返します。
{
"status": "ok",
"ip": "10.0.0.5",
"version": 4,
"found": false
}明示的なフォールバックの経路を作る
空のresults配列、またはfound: falseのチェックは、成功時の処理とも、4xxおよび5xxレスポンスのエラー処理とも別の、独立した分岐としてコードに組み込んでください。次に何をするかは意図的に決めておきます。ユーザーに入力内容の絞り込みを求める、limitを大きくしたより広い検索にフォールバックする、あるいは空白や誤解を招くデフォルト値ではなく、「場所が見つかりません」という明確なメッセージを表示する、といった対応です。
まず確認すべきよくある原因
本当に存在しない場所であることも原因の一つですが、形式の整っていない入力文字列、タイプミス、予期せず複数の言語や文字体系が混ざったクエリも、実際に存在する住所に対して空の結果を返す原因になります。その場所自体が存在しないと判断する前に、入力を正規化するか、countriesパラメータを設定したバージョンを試すことで解決しないか検討してください。
空の結果を分けて記録する
連携で空の結果の経路に入る頻度を、エラー率とは別に追跡してください。空の結果の割合が増えている場合、それは検索そのものの問題ではなく、住所の収集方法や形式など、上流のデータ品質の問題を示していることがよくあります。
結果なしの検索のコスト
空の結果でも、一致が見つかった場合と同じく1リクエストとしてカウントされます。どちらの場合も検索は実行されているためです。結果が空だった検索に対する割引料金は別途ありません。
空の結果を、エラー処理に後から付け足したものではなく、独立した意図的な結果として扱うことで、連携は目に見えて堅牢になります。実際のエラーレスポンスについてはエラーのページで説明しており、空の結果については、ジオコーディングのドキュメントなど、各エンドポイントの通常のレスポンス形式とあわせて記載しています。