My Geocode

ガイド

郵便番号と国を組み合わせて検索を高速化する

· 3分で読めます · My Geocode · #郵便番号#パフォーマンス#ジオコーディング

ジオコーディングは雑多な自由テキストを扱えるように作られているため、見えないところで、どのような種類の入力を受け取っているのかを判断する処理を行っています。きれいな郵便番号と国がすでに手元にあることがわかっているなら、より直接的な方法があります。

postcodeエンドポイントを直接使う

自由テキストの文字列を組み立てて/v1/forwardに送る代わりに、郵便番号と国を直接/v1/postcodeに送ります。

GET /v1/postcode?code=90210&country=US
{
  "status": "ok",
  "postcode": "90210",
  "country_code": "US",
  "results": [
    {"lat": 34.0901, "lon": -118.4065, "components": {"city": "Beverly Hills", "region": "CA", "country": "US"}}
  ]
}

こちらのほうが適している理由

郵便番号と国の組み合わせはすでに完全に構造化された入力なので、似た表記の複数の場所に一致しうる自由テキストの文字列とは違い、エンドポイントが解決すべき曖昧さがありません。まさにこの入力形式のために作られたエンドポイントを使うことで、予期しない結果のリスクを抑えながら、よりきれいな一致が得られます。

2つ目の例：英数字の郵便番号

数字だけでなく文字と数字を組み合わせて使う国でも、同じ呼び出しがまったく同じように機能します。

GET /v1/postcode?code=K1A 0B1&country=CA

これを確実にしているのはcountryパラメータを渡すことです。コードの文字列だけでは国をまたいで一意であるとは限らず、どの郵便制度に照らして解釈すべきかをエンドポイントに伝えるのがcountryパラメータだからです。

それでもジオコーディングが必要な場合

郵便番号がカバーする大まかなエリアではなく、特定の番地レベルの一致が必要な場合は、完全な住所を使ったジオコーディングが引き続き適切なツールです。郵便番号検索は、その番号がカバーするエリアに解決されるのであって、その中の特定の建物に解決されるわけではないからです。配送エリアの検証のようなエリアレベルの検索には/v1/postcodeを、建物レベルの精度が必要な場合は/v1/forwardを使ってください。

避けるべきよくある間違い

郵便番号が常にちょうど1つの地点に対応し、その中のすべての住所を正確に表していると考えないでください。/v1/postcodeが返す座標はその郵便番号がカバーするエリアを表しており、それは1つの街区のこともあれば、国によってはずっと広い区域のこともあります。返された地点を、郵便番号全体の代表点としてではなく、特定の顧客の建物の正確な位置であるかのように扱うと、その上に構築した距離に左右される処理すべてに誤差が入り込みます。

ワークフローで両方を組み合わせる

よくあるパターンは、まず/v1/postcodeで郵便番号と国の組み合わせを検証し、それが通ったら番地までの完全な住所を/v1/forwardに送って正確な座標を取得するというものです。1つのエンドポイントに両方の役割を無理にさせるのではなく、各段階に1回ずつ、1件の送信につき2回のリクエストになります。

エッジケース：結果を返さない郵便番号

results配列が空の場合は、指定された国ではその郵便番号が認識されなかったことを意味し、エラーレスポンスとは異なる状況です。システムエラーとして表示するのではなく、ほかの認識できない入力と同じように扱い、入力内容をもう一度確認するよう顧客に求めてください。

コスト

郵便番号検索は1回につき1リクエストで、ジオコーディングの検索と同じコストです。構造化された入力に適したエンドポイントを選んでもコストは変わりません。変わるのは、正しい結果にどれだけ直接たどり着けるかです。

きれいに構造化された入力がすでにあるときにpostcodeエンドポイントを使えば、自由テキストの文字列を組み立て直して、それをまた分解して解析するときに生じる余計な曖昧さを避けられます。詳しくは郵便番号検索のドキュメントをご覧ください。

ガイドのその他の記事

· 4分で読めます

住所と郵便番号を照合する

住所と郵便番号をそれぞれ個別に解決して実際に示す内容を比較することで、注文の発送前に番地と郵便番号の不一致を見つけます。