Geocoding v3 から v4 に移行する

欧州経済領域（EEA）のデベロッパー

Geocoding API v4 では、API の v3 の機能を置き換えるいくつかの新しいメソッドが導入されています。このガイドでは、新しい v4 メソッドを使用するようにアプリを移行する方法について説明します。

既存の API キーを新しい v4 メソッドで使用できます。ただし、API の v3 で割り当ての引き上げをリクエストした場合は、新しい v4 API で引き上げをリクエストする必要があります。

v3 のフォワード ジオコーディングから移行する

v3 Geocoding を使用して住所をジオコーディングしている場合は、GET リクエストを受け入れる v4 の 住所をジオコーディングするメソッドに移行する必要があります。

v4 API では、いくつかのパラメータの名前、構造、サポートが変更されています。レスポンスで返すフィールドを指定するには、フィールド マスクを使用することを強くおすすめします。

リクエスト パラメータの変更

v3 パラメータ v4 パラメータ メモ
address、components address 非構造化アドレス（v3 address）が URL パスで渡されるようになりました。構造化された住所コンポーネント（v3 components）は、address.* クエリ パラメータとして渡すことができます。v3 コンポーネント フィルタを再現するをご覧ください。
bounds locationBias.rectangle 名前を変更し、構造をオブジェクトに変更しました。
language languageCode 名前を変更しました。省略した場合、v3 では Accept-Language ヘッダーが使用されるか、デフォルトで en が使用されます。一方、v4 では、デフォルトでその場所の現地の言語と文字が使用されます。
region regionCode 名前を変更しました。省略した場合、v3 はデフォルトで us になりますが、v4 にはデフォルト値はありません。
extra_computations 削除済み SearchDestinations メソッドに置き換えられました。

レスポンス フィールドの変更

v3 フィールド v4 フィールド メモ
status、error_message 削除済み v4 では HTTP ステータス コードとエラー本文が使用されます。
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText 名前を変更しました。
results.geometry.location_type results.granularity 名前を変更しました。
results.geometry.location results.location フィールド名: lat/lng -> latitude/longitude。
results.geometry.viewport results.viewport フィールド名: northeast/southwest -> high/low。
results.postcode_localities results.postalCodeLocalities 名前を変更しました。1 つ以上の地域で返されるようになりました（v3 では 1 より大きい値が必要です）。
results.partial_match 削除済み
新機能 results.addressComponents.languageCode 特定のアドレス コンポーネントの言語。
新機能 results.bounds high/low を使用した明示的な境界。
新機能 results.place 場所のリソース名。
新機能 results.postalAddress 構造化された PostalAddress オブジェクト。

v3 コンポーネント フィルタを再現する

Geocoding v3 のフォワード ジオコーディングには、特定のコンポーネント（components=country:US など）の結果を厳密にフィルタリングできる components パラメータが含まれていました。v4 のフォワード ジオコーディングでは、リクエスト パラメータでこのタイプの厳密なフィルタリングはサポートされていません。v4 では、パス内の単一の非構造化文字列として、または address.addressLines、address.locality、address.administrativeArea、address.postalCode、address.regionCode などの構造化されたクエリ パラメータとして、アドレス情報を提供できます。構造化パラメータはハードフィルタとして機能しません。代わりに、指定されたすべてのコンポーネントが結合され、API がジオコーディングを試みる完全な住所が形成されます。API は、指定された住所全体に最も一致するものをすべてのコンポーネントで検索します。コンポーネントを構造化された方法で提供すると、特に住所情報が別々のフォーム フィールドから収集される場合に、API が意図をよりよく理解するのに役立ちます。各フィールドの情報タイプが明確であるため、API は各コンポーネント内の軽微なタイプミスや曖昧さを処理できます。

v3 のハード コンポーネント フィルタと同様の動作を実現するには、レスポンスの postalAddress オブジェクトと addressComponents オブジェクトに基づいて、v4 API から返された results 配列にクライアントサイド フィルタを実装する必要があります。

次の表に、v3 components フィルタと v4 postalAddress フィールドの最適な一致を示します。

v3 コンポーネント フィルタ v4 レスポンス フィールド
country postalAddress.regionCode
postal_code postalAddress.postalCode
administrative_area postalAddress.administrativeArea または addressComponents

クライアントサイドのフィルタリングの例

次の例は、結果をフィルタリングして、サポートされているフィールド（国、行政区域、郵便番号）の v3 コンポーネント フィルタリングと同様の動作を実現する方法を示しています。信頼できるフィルタリング条件が存在しないため、他のフィールドでフィルタリングすることはおすすめしません。

国でフィルタ

リクエストの address.regionCode と各結果の postalAddress.regionCode を照合します。なお、API はリクエストで小文字の地域コードを受け入れますが、レスポンスでは常に大文字で返します。そのため、比較する前に、入力を大文字に正規化する必要があります。

Python コードの例 
def filter_by_country(results, region_code):
    return [
        res for res in results
        if res.get('postalAddress', {}).get('regionCode') == region_code.upper()
    ]

# Example usage:
# v4_response = ... # API call response
# filtered = filter_by_country(v4_response.get('results', []), 'US')
Node.js コードの例 
function filterByCountry(results, regionCode) {
    return results.filter(res => res.postalAddress?.regionCode === regionCode.toUpperCase());
}

// Example usage:
// const v4Response = ... # API call response
// const filtered = filterByCountry(v4Response.results, 'US');
行政区域でフィルタ

リクエストの address.administrativeArea と各結果の postalAddress.administrativeArea を照合します。国コードと同様に、比較する前に大文字に正規化する必要があります。これは、リクエストの administrativeArea に標準の 2 文字の略語が指定されている場合にのみ信頼できます。レスポンスの postalAddress.administrativeArea が ISO 3166-2 コードのサフィックスと直接一致しない理由はいくつかあります。まず、一部の地域では、ISO 3166-2 コードに対応する区分が郵便番号の標準的な表記に含まれていません。たとえば、スペインでは、行政区域レベル 1（例: カナリア諸島の「CN」）が addressComponents に含まれる場合がありますが、postalAddress.administrativeArea にはレベル 2 の地域（例: 「サンタ クルス デ テネリフェ」）が含まれる場合があります。次に、一部の地域では、区画の略称は一般的に使用されておらず、postalAddress.administrativeArea で長い名前で表されます（同様の理由で、区画に対応する住所コンポーネントの addressComponents.shortText が区画の ISO 3166-2 コードの接尾辞と一致しない場合があります）。また、場合によっては、n が 1 より大きい administrative_area_level_n の住所コンポーネントでサブディビジョンが表されることもあります。 最も包括的な結果を得るには、postalAddress.administrativeArea と、administrative_area_level_n タイプ（administrative_area_level_1 など）の addressComponents の両方で一致を確認する必要があります。

Python コードの例 
def filter_by_admin_area(results, admin_area):
    target = admin_area.upper()
    filtered = []
    for res in results:
        # Check postalAddress
        pa_aa = res.get('postalAddress', {}).get('administrativeArea', '')
        if pa_aa == target:
            filtered.append(res)
            continue
        # Check all administrative area levels in addressComponents
        for comp in res.get('addressComponents', []):
            is_admin_level = any(t.startswith('administrative_area_level_')
                               for t in comp.get('types', []))
            if is_admin_level:
                short = comp.get('shortText', '')
                if short == target:
                    filtered.append(res)
                    break
    return filtered

# Example usage:
# filtered = filter_by_admin_area(v4_response.get('results', []), 'CA')
Node.js コードの例 
function filterByAdminArea(results, adminArea) {
    const target = adminArea.toUpperCase();
    return results.filter(res => {
        // Check postalAddress.administrativeArea
        if (res.postalAddress?.administrativeArea === target) {
            return true;
        }
        // Check addressComponents for any administrative area level
        return res.addressComponents?.some(c => {
            const isAdmin = c.types?.some(t => t.startsWith('administrative_area_level_'));
            return isAdmin && c.shortText === target;
        });
    });
}

// Example usage:
// const filtered = filterByAdminArea(v4Response.results, 'CA');
郵便番号でフィルタ

リクエストの address.postalCode と各結果の postalAddress.postalCode を照合します。比較する前に、入力郵便番号と結果の郵便番号の両方を正規化する必要があります。正規化ロジックはリージョンに大きく依存します。基本的なアプローチでは、スペースとハイフンを削除し、大文字と小文字を統一します。

郵便番号の接頭辞（英国の「L2」など）や接尾辞（米国の郵便番号の「+4」など）を処理するには、より高度な正規化が必要になる場合があります。必要な正規化ロジックは、国と関連する郵便番号の形式によって異なります。提供されている正規化関数を調整するか、ターゲットとする地域に対してより高度なロジックを実装する必要があるかもしれません。

提供されている例では、米国の郵便番号を処理し、ZIP+4 が提供または返された場合でも、5 桁のベースで一致させることができます。

Python コードの例（米国の郵便番号に焦点を当てたもの） 
import re

def normalize_postal_code_us(pc):
    # Basic normalization for US: uppercase, alphanumeric only
    if not pc:
        return ""
    normalized = re.sub(r'[^A-Z0-9]', '', pc.upper())
    # Return only the first 5 digits for US ZIP codes
    return normalized[:5]

def filter_by_postal_code_us(results, postal_code):
    normalized_input = normalize_postal_code_us(postal_code)
    if not normalized_input:
        return []
    filtered_results = []
    for res in results:
        pa_pc = res.get('postalAddress', {}).get('postalCode', '')
        if normalize_postal_code_us(pa_pc) == normalized_input:
            filtered_results.append(res)
    return filtered_results

# Example usage:
# Matches '94043', '94043-1351', '940431351'
# filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043')
# filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043-1234')
Node.js コードの例（米国の郵便番号に焦点を当てたもの） 
function normalizePostalCodeUs(pc) {
    // Basic normalization for US: uppercase, alphanumeric only
    const normalized = (pc || '').toUpperCase().replace(/[^A-Z0-9]/g, '');
    // Return only the first 5 digits for US ZIP codes
    return normalized.substring(0, 5);
}

function filterByPostalCodeUs(results, postalCode) {
    const normalizedInput = normalizePostalCodeUs(postalCode);
    if (!normalizedInput) {
        return [];
    }
    return results.filter(res => {
        const paPc = res.postalAddress?.postalCode || '';
        return normalizePostalCodeUs(paPc) === normalizedInput;
    });
}

// Example usage:
// Matches '94043', '94043-1351', '940431351'
// const filtered = filterByPostalCodeUs(v4Response.results, '94043');
// const filtered = filterByPostalCodeUs(v4Response.results, '94043-1234');

v3 リバース ジオコーディングから移行する

v3 リバース ジオコーディングを使用して座標を住所に変換している場合は、GET リクエストを受け入れる v4 の場所のリバース ジオコーディング メソッドに移行する必要があります。

v4 API では、いくつかのパラメータの名前、構造、サポートが変更されています。レスポンスで返すフィールドを指定するには、フィールド マスクを使用することを強くおすすめします。

リクエスト パラメータの変更

v3 パラメータ v4 パラメータ メモ
language languageCode 名前を変更しました。省略した場合、v3 では Accept-Language ヘッダーが使用されるか、デフォルトで en が使用されます。一方、v4 では、デフォルトでその場所の現地の言語と文字が使用されます。
region regionCode 名前を変更しました。省略すると、v3 のデフォルトは us になりますが、v4 にはデフォルト値がありません。
result_type types 名前が変更されました。繰り返しクエリ パラメータを使用します。
location_type granularity 名前が変更されました。繰り返しクエリ パラメータを使用します。
extra_computations 削除済み SearchDestinations メソッドに置き換えられました。

レスポンス フィールドの変更

v3 フィールド v4 フィールド メモ
status、error_message 削除済み v4 では HTTP ステータス コードとエラー本文が使用されます。
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText 名前を変更しました。
results.geometry.location_type results.granularity 名前を変更しました。
results.geometry.location results.location フィールド名: lat/lng -> latitude/longitude。
results.geometry.viewport results.viewport フィールド名: northeast/southwest -> high/low。
新機能 results.addressComponents.languageCode 特定のアドレス コンポーネントの言語。
新機能 results.bounds high/low を使用した明示的な境界。
新機能 results.place 場所のリソース名。
新機能 results.postalAddress PostalAddress 構造化オブジェクト。

v3 のアドレス記述子から移行する

address_descriptor を使用して Geocoding v3 で場所に関する追加情報を取得している場合は、SearchDestinationsResponse の landmarks フィールドを使用するように移行する必要があります。

v3 Place ジオコーディングから移行する

place_id を使用して Geocoding v3 で特定のプレイス ID の住所を取得している場合は、GET リクエストを受け入れる v4 の Place Geocoding メソッドに移行する必要があります。

v4 API では、いくつかのパラメータの名前、構造、サポートが変更されています。レスポンスで返すフィールドを指定するには、フィールド マスクを使用することを強くおすすめします。

リクエスト パラメータの変更

v3 パラメータ v4 パラメータ メモ
place_id リクエスト proto の place フィールド プレイス ID は、パスパラメータ places/{place}（例: https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw）として指定されるようになりました。これは、基盤となるリクエストの place フィールドにマッピングされます。
language languageCode 名前を変更しました。省略した場合、v3 では Accept-Language ヘッダーが使用されるか、デフォルトで en が使用されます。一方、v4 では、デフォルトでその場所の現地の言語と文字が使用されます。
region regionCode 名前を変更しました。省略した場合、v3 はデフォルトで us になりますが、v4 にはデフォルト値はありません。

レスポンス フィールドの変更

v3 フィールド v4 フィールド メモ
status、error_message 削除済み v4 では HTTP ステータス コードとエラー本文が使用されます。
results （ルート） v4 は results 配列ではなく、単一の結果オブジェクトを返します。
results.address_components.long_name / results.address_components.short_name addressComponents.longText / addressComponents.shortText 名前を変更しました。
results.geometry.location_type granularity 名前を変更しました。
results.geometry.location location フィールド名: lat/lng -> latitude/longitude。
results.geometry.viewport viewport フィールド名: northeast/southwest -> high/low。
results.postcode_localities postalCodeLocalities 名前を変更しました。1 つ以上の地域に対して返されるようになりました（v3 では 1 つ以上が必要）。
新機能 addressComponents.languageCode 特定のアドレス コンポーネントの言語。
新機能 bounds high/low を使用した明示的な境界。
新機能 place 場所のリソース名。
新機能 postalAddress PostalAddress 構造化オブジェクト。

Geocoding Hyperlocal Data から Destinations に移行する

Geocoding API v3 の次の機能は、Geocoding API v4 の SearchDestinations メソッドに置き換えられます。

  • 閲覧開始数
  • ナビゲーション ポイント
  • 建物の輪郭
  • 邸宅と庭園

上記の機能に Geocoding API v3 を使用していた場合は、このドキュメントを参考にして、代わりに SearchDestinations メソッドを使用してこれらの機能を取得してください。このドキュメントでは、SearchDestinations レスポンスでこれらの機能を確認する場所と、Geocoding API v3 と Geocoding API v4 の SearchDestinations メソッドの間で、これらの機能が API レスポンスでどのように表現されるかの違いについて説明します。

閲覧開始数

destination に関連付けられた入口を取得するには、destination.entrances フィールドを使用します。

entrance の形式は、Geocoding API v3 のエントランス形式と若干異なります。destination.entrances の各エントランスには、次のフィールドがあります。

  • displayName - これは、入り口のわかりやすい名前（「ゲート B」など）を指定する新しいオプション フィールドです。
  • location - これは LatLng タイプの場所です。Geocoding API v3 で使用される形式とは異なります。
  • tags - Geocoding API v3 のエントランスの tags フィールドと同じです。
  • place - Geocoding API v3 のエントランスの buildingPlaceId フィールドに類似しています。ただし、このフィールドのプレイス ID は、建物だけでなく、あらゆるタイプのプレイスを対象とすることができます。

destination に関連付けられたナビゲーション ポイントを取得するには、destination.navigationPoints フィールドを使用します。

navigationPoint の形式は、Geocoding API v3 のナビゲーション ポイントの形式とは若干異なります。destination.navigationPoints の各ナビゲーション ポイントには、次のフィールドがあります。

  • displayName - これは、ナビゲーション ポイントの人間が読める名前（「5th Ave」など）を含む新しいオプション フィールドです。
  • location - LatLng タイプの位置情報です。Geocoding API v3 で使用されている形式とは異なります。
  • travelModes - これは、Geocoding API v3 のナビゲーション ポイントの restrictedTravelModes フィールドに似ています。使用可能な列挙値は同じですが、唯一の違いは、このフィールドが、制限された移動手段ではなく、ナビゲーション ポイントで許可される移動手段を表すようになったことです。
  • usage - ナビゲーション ポイントでサポートされているユースケースを含む新しいフィールド。

建物の輪郭

destination に関連付けられた建物の輪郭を取得するには、建物を表す destination の placeView オブジェクトの displayPolygon フィールドを使用する必要があります。各 placeView について、placeView.structureType フィールドで建物かどうかを確認できます。構造タイプが BUILDING の場合、placeView.displayPolygon フィールドからアウトラインを取得できます。placeView には、Geocoding API v3 にはなかった建物の追加フィールドも含まれます。

destination には、次のフィールドの建物を示す placeView オブジェクトを含めることができます。

  • destination.primary - 目的地の主要な場所です。
  • destination.containingPlaces - これは、メインの場所を「含む」より大きな場所を保持できる繰り返しフィールドです。たとえば、プライマリ プレイスが subpremise の場合、通常、containingPlaces には建物を表す placeView が保持されます。
  • destination.subDestinations - これは、メインの場所のサブ目的地を保持できる繰り返しフィールドです。たとえば、建物の個々のマンションのユニットなどです。通常、このフィールドには建物を表す placeView はありません。

placeView.displayPolygon の形式は、Geocoding API v3 の建物のアウトライン形式（GeoJSON 形式、RFC 7946 形式を使用）と一致します。

邸宅と庭園

建物の外形と同様に、destination に関連付けられた敷地を取得するには、敷地を表す destination 内の placeView オブジェクトの displayPolygon フィールドを使用する必要があります。各 placeView について、placeView.structureType フィールドを使用して根拠かどうかを確認できます。構造体の型が GROUNDS の場合、placeView.displayPolygon フィールドからアウトラインを取得できます。また、placeView には、Geocoding API v3 になかった理由を示す追加フィールドも含まれます。

destination には、次のフィールドに敷地を表す placeView オブジェクトを含めることができます。

  • destination.primary
  • destination.containingPlaces
  • destination.subDestinations

placeView.displayPolygon の形式は、Geocoding API v3 の敷地外形形式（GeoJSON 形式）と一致します。これは、RFC 7946 形式を使用しています。

結果の精度

Geocoding API v3 では、レスポンス ジオメトリの location_type フィールドは結果の精度を示し、一部のクライアントはこれらの値（ROOFTOP、RANGE_INTERPOLATED、GEOMETRIC_CENTER、APPROXIMATE）に基づいて結果をランク付けまたはフィルタしていました。標準の Geocoding API v4 移行では、このフィールドの名前が granularity に変更されます。

Destinations API（v4 SearchDestinations）には、location_type フィールドはありません。代わりに、空間情報は次のように処理されます。

  • クライアントサイドで手動フィルタリングを行う必要がない: 標準のジオコーディングでは、さまざまな粒度で複数の結果が提供されますが、SearchDestinations メソッドでは、可能な限り単一の最適化された目的地に解決することで、あいまいさを最小限に抑えます。これにより、クライアントは場所のタイプでフィルタして最適な結果を判断する必要がなくなります。
  • 構造タイプと表示ポリゴンで表される空間情報: 空間ジオメトリと構造は、以下によって示されます。
    • displayPolygon（正確なジオメトリの場合）。
    • placeView オブジェクト内の structureType フィールド。
  • 構造型マッピング:
    • POINT、BUILDING、SECTION の structureType は、通常、以前に ROOFTOP と呼ばれていたものに対応します。
    • 通常、GROUNDS の structureType は GEOMETRIC_CENTER に対応します。

フィールド マスクを使用してこれらの機能をリクエストする

SearchDestinations メソッドには、返すフィールドを選択するで説明されているように、フィールド マスクが必要です。すべてのフィールドを返すようにフィールド マスクを * に設定することも、受信する特定のフィールドに設定することもできます。たとえば、次の API リクエストでは、目的地の入口、ナビゲーション ポイント、建物の輪郭、敷地を取得するために必要なすべてのフィールドを受け取るようにフィールド マスクを設定しています。

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4/geocode/destinations

セキュリティ上の考慮事項

Geocoding API v4 は、サーバー間 API として設計されています。JavaScript ユーザーが v3 から v4 に直接移行する方法はありません。API キーを使用してクライアントサイドの JavaScript（ブラウザなど）から v4 メソッドを直接呼び出すと、API キーが盗難や不正使用のリスクにさらされます。

HTTP リファラー制限は便利ですが、リクエストの Referer ヘッダーを偽造する攻撃者によって簡単にバイパスされる可能性があるため、ウェブサービス エンドポイントの保護としては不十分です。

Geocoding API v4 は、独自のバックエンド サーバーから使用することをおすすめします。クライアント アプリケーションは、この中間サーバーにリクエストを送信する必要があります。中間サーバーは、保護された API キー（環境変数や Secret Manager に保存されているキーなど）を使用して Google API を安全に呼び出します。これにより、API キーがフロントエンド コードで公開されることがなくなります。

クライアントサイドのニーズに対応する代替手段

ジオコーディングを必要とするクライアントサイドのニーズがある場合は、既存のクライアントサイド ソリューションのいずれかを使用することを検討してください。