Geocoding v3 から v4 に移行する

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

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

v3 順方向ジオコーディングから移行する

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

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

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

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

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 コンポーネントのフィルタリングと同様の動作を実現するために、結果をフィルタリングする方法を示しています。信頼できるフィルタリング条件が存在しないため、他のフィールドでフィルタリングすることはおすすめしません。

国でフィルタ

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

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')

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 コードの接尾辞と一致しない場合があります）。また、場合によっては、administrative_area_level_n の住所コンポーネントで n が 1 より大きい場合、細分化が表されることがあります。最も包括的な結果を得るには、postalAddress.administrativeArea と administrative_area_level_n 型（administrative_area_level_1 など）の addressComponents の両方で一致を確認する必要があります。

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')

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 桁のベースで照合できます。

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')

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 アドレス記述子から移行する

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

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

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

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

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

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

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 - これは新しいオプション フィールドで、入り口の人間が読める名前（例: 「Gate B」）が設定されます。
• location - LatLng タイプの位置情報です。Geocoding API v3 で使用される形式とは異なります。
• tags - Geocoding API v3 のエントランスの tags フィールドと同じです。
• place - Geocoding API v3 のエントランスの buildingPlaceId フィールドに類似しています。ただし、このフィールドのプレイス ID は、建物だけでなく、あらゆるタイプの場所の 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 の形式は、RFC 7946 形式を使用した GeoJSON 形式である Geocoding API v3 の建物の輪郭形式と一致します。

邸宅と庭園

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

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

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

placeView.displayPolygon の形式は、RFC 7946 形式を使用した GeoJSON 形式である Geocoding API v3 のグラウンド アウトライン形式と一致します。

結果の精度

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 キー（環境変数またはシークレット マネージャーに保存されたキーなど）を使用して Google API を安全に呼び出します。これにより、API キーがフロントエンド コードで公開されることはありません。

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

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

• Maps JavaScript API のジオコーディング サービス: ジオコーディング サービスは引き続き v3 バックエンドを使用し、ブラウザ環境での使用を想定して設計されています。
• Places UI キット: 住所関連のユーザー インターフェース要素には、Place Autocomplete 要素などの Places UI キットを使用します。