对地址进行地理编码

欧洲经济区 (EEA) 开发者

地理编码会将地址转换为地图上的某个位置。对地址进行地理编码时，响应包含以下信息：

  • 相应位置的地点 ID
  • 相应位置的纬度和经度坐标
  • 营业地点的 Plus Code
  • 展开的地址详情

地理编码请求

地理编码请求是一种 HTTP GET 请求。您可以将地址指定为非结构化字符串：

https://geocode.googleapis.com/v4/geocode/address/ADDRESS_STRING

或者，以由查询参数表示的结构化地址组成部分集的形式：

https://geocode.googleapis.com/v4/geocode/address?STRUCTURED_ADDRESS

在处理 HTML 表单中捕获的地址组成部分时，您通常会使用结构化格式。

将所有其他参数作为网址参数传递，或者对于 API 密钥和字段掩码等参数，在标头中作为 GET 请求的一部分传递。

传递非结构化地址字符串

非结构化地址是指格式为字符串或 Plus Code 的地址。 地址地理编码无法解析纬度和经度坐标，也无法解析不表示地址或 Plus Code 的其他非结构化字符串。不支持使用此类字符串的请求，此类请求可能会导致错误响应或未指定的行为。不支持的查询示例包括：

查询类型 示例
纬度和经度坐标。请改用反向地理编码。 "37.422131,-122.084801"
概念或限制条件过多，例如在单个查询中包含多个地点、道路或城市的名称 “Market Street San Francisco San Jose Airport”
Google 地图上未显示的邮政地址元素 "C/O John Smith 123 Main Street"
"P.O. Box 13 San Francisco"
商家、连锁店或类别的名称与这些实体未覆盖的地点相结合 “德克萨斯州达拉斯附近的 Tesco”
具有多种解读的模糊查询 “充电器送达”
不再使用的历史名称 "Middlesex United Kingdom"
非地理空间元素或意图 “文图拉港有多少艘船？”
非官方名称或自选名称 "The Jenga"
"The Helter Skelter"

例如，以下示例传递了网址编码的地址字符串“1600 Amphitheatre Parkway, Mountain View, CA”：

https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY

请注意，网址中的“+”字符会转换为空格。

您还可以使用 curl 命令发出请求：

curl -H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

地址可以包含多种类型的特殊字符。例如，“7/1 King St, Concord West”中的“/”。将“/”网址编码为 %2F：

https://geocode.googleapis.com/v4/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

另一个常见示例是“#”字符，例如“9500 W Bryn Mawr Ave #650, Rosemont”。将“#”网址编码为 %2FE：

https://geocode.googleapis.com/v4/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

在下一个示例中，您将指定一个非结构化地址字符串作为 Plus Code 849VCWC8+R4。确保您将“+”字符进行网址编码，编码为 %2B：

https://geocode.googleapis.com/v4/geocode/address/849VCWC8%2BR4?key=API_KEY

传递结构化地址

使用 address 查询参数（类型为 PostalAddress）指定结构化地址。借助 PostalAddress 对象，您可以在请求中将部分或所有地址组成部分指定为单独的查询参数。

例如，如需仅指定地址的邮政编码，请使用 PostalAddress.postalCode：

https://geocode.googleapis.com/v4/geocode/address?address.postalCode=01062&key=API_KEY

如需指定多个地址组成部分（例如 HTML 表单中捕获的地址组成部分），请使用多个查询参数：

https://geocode.googleapis.com/v4/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View&address.administrativeArea=CA&key=API_KEY

使用 OAuth 发出请求

Geocoding API v4 支持使用 OAuth 2.0 进行身份验证。如需将 OAuth 与 Geocoding API 搭配使用，必须为 OAuth 令牌分配正确的范围。Geocoding API 支持以下范围，可用于正向地理编码：

  • https://www.googleapis.com/auth/maps-platform.geocode - 与所有 Geocoding API 方法搭配使用。
  • https://www.googleapis.com/auth/maps-platform.geocode.address - 仅与 GeocodeAddress 搭配使用，用于正向地理编码。

此外，您还可以为所有 Geocoding API 方法使用常规 https://www.googleapis.com/auth/cloud-platform 范围。此范围在开发期间很有用，但在生产环境期间则不然，因为这是一个允许访问所有方法的通用范围。

如需了解详情和示例，请参阅使用 OAuth。

地理编码响应

地理编码会返回一个 GeocodeAddressResponse 对象，其中包含 GeocodeResult 对象的 results 数组。每个 GeocodeResult 对象都表示一个地点。

完整的 JSON 对象采用以下格式：

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCWC8+R4",
        "compoundCode": "CWC8+R4 Mountain View, CA, USA"
      }
    }
  ]
}

必需参数

  • address - 要进行地理编码的街道地址或 Plus Code。注意：地址地理编码无法解析纬度和经度坐标，也无法解析不表示地址或 Plus Code 的其他非结构化字符串。如需详细了解不受支持的查询并查看相关示例，请参阅传递非结构化地址字符串。 根据相关国家/地区的邮政服务所使用的格式指定地址。应避免使用其他地址元素，例如企业名称以及单元号、房间号或楼层号。街道地址元素应以空格分隔，并进行网址编码，编码为 %20。例如，传递地址“24 Sussex Drive Ottawa ON”时，应采用以下格式： 
    24%20Sussex%20Drive%20Ottawa%20ON
     按如下所示设置 Plus Code 的格式。加号经网址编码为 %2B，空格经网址编码为 %20：
    • 全局代码是包含 4 个字符的区号和至少包含 6 个字符的区域代码。例如，将“849VCWC8+R9”编码为 849VCWC8%2BR9。
    • 混合代码是至少包含 6 个字符的区域代码，具有明确的位置信息。例如，将“CWC8+R9 Mountain View, CA, USA”编码为 CWC8%2BR9%20Mountain%20View%20CA%20USA。

可选参数

  • locationBias

    指定要搜索的区域，格式为 Viewport。 此位置用作偏差，这意味着可以返回指定位置附近的结果，包括该区域附近但不在该区域内的结果。

    将区域指定为矩形视口。矩形是一个纬度-经度视口，表示为两个对角相对的低点和高点。低点标记矩形的西南角，高点表示矩形的东北角。

    视口被视为一个闭合区域，这意味着它包含其边界。纬度范围必须介于 -90 度到 90 度之间（含），经度范围必须介于 -180 度到 180 度之间（含）：

    • 如果 low = high，则视口由该单个点组成。
    • 如果 low.longitude > high.longitude，则经度范围会反转（视口会跨越 180 度经度线）。
    • 如果 low.longitude = -180 度且 high.longitude = 180 度，则视口包含所有经度。
    • 如果 low.longitude = 180 度且 high.longitude = -180 度，则经度范围为空。
    • 如果 low.latitude > high.latitude，则纬度范围为空。

    必须同时填充下限和上限，并且所表示的框不得为空。空视口会导致错误。

    例如，此查询字符串定义了一个完全包含纽约市的视口：

    ?locationBias.rectangle.low.latitude=40.477398&locationBias.rectangle.low.longitude=-74.259087&locationBias.rectangle.high.latitude=40.91618&locationBias.rectangle.high.longitude=-73.70018

  • languageCode

    返回结果所用的语言。

    • 请参阅支持的语言列表。Google 会经常更新支持的语言，因此该列表可能并非详尽无遗。
    • 如果未提供 languageCode，则 API 默认为 en。如果您指定的语言代码无效，API 会返回 INVALID_ARGUMENT 错误。
    • 该 API 会尽力提供用户和当地人都能看懂的街道地址。为了实现这一目标，它会返回本地语言的街道地址，并在必要时根据首选语言将地址音译为用户可读的文字。所有其他地址均以首选语言返回。地址组成部分全部以同一种语言返回，该语言是从第一个组成部分中选择的。
    • 如果首选语言中没有相应名称，API 会使用最接近的匹配项。
    • 首选语言对 API 选择返回的结果集以及返回顺序有较小的影响。地理编码器会根据语言以不同的方式解读缩写，例如街道类型的缩写，或者在一种语言中有效但在另一种语言中无效的同义词。

  • regionCode

    地区代码，以 双字符 CLDR 代码值表示。没有默认值。大多数 CLDR 代码都与 ISO 3166-1 代码相同。

    在对地址进行地理编码（即正向地理编码）时，此参数可以影响但不会完全限制服务返回指定区域的结果。在对位置或地点进行地理编码时（反向地理编码或地点地理编码），可以使用此参数设置地址格式。在任何情况下，此参数都可能会根据适用法律影响结果。

  • FieldMask

    创建响应字段掩码，以指定要在响应中返回的字段。使用网址参数 $fields 或 fields，或者使用 HTTP 标头 X-Goog-FieldMask，将响应字段掩码传递给相应方法。例如，以下请求将仅返回响应的 placeID 字段。

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
    响应如下： 
    {
  "results": [
    {
      "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc"
    }
  ]
}

    如需了解详情，请参阅选择要返回的字段。

位置信息偏差

使用 locationBias 参数指示地理编码服务优先显示给定视口（表示为边界框）中的结果。locationBias 参数定义了此边界框的西南角和东北角的纬度/经度坐标。

例如，针对地址“华盛顿”的地理编码请求可以返回华盛顿特区和美国华盛顿州的结果：

https://geocode.googleapis.com/v4/geocode/address/Washington?key=API_KEY

响应的格式如下：

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "location": {
        "latitude": 38.9071923,
        "longitude": -77.0368707
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "bounds": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "formattedAddress": "Washington, DC, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "Washington",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "location": {
        "latitude": 47.7510741,
        "longitude": -120.7401386
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024945,
          "longitude": -116.91607109999998
        }
      },
      "bounds": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024442,
          "longitude": -116.91607109999998
        }
      },
      "formattedAddress": "Washington, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "WA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
      ...
      ],
      "types": [
        "administrative_area_level_1",
        "political"
      ]
    }
  ]
}

不过，如果我们添加一个 locationBias 参数，将边界框定义在美国东北部周围，那么此地理编码会仅返回华盛顿特区：

https://geocode.googleapis.com/v4/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72&locationBias.rectangle.high.latitude=43.39&locationBias.rectangle.high.longitude=-65.90&key=API_KEY

区域加权

在地理编码请求中，您可以使用 regionCode 参数指示地理编码服务返回偏向特定地区的结果。此参数采用 双字符 CLDR 代码值，用于指定地区偏差。大多数 CLDR 代码都与 ISO 3166-1 代码相同。

regionCode 没有默认值。例如，“Toledo”的地理编码会返回美国和西班牙的结果：

https://geocode.googleapis.com/v4/geocode/address/Toledo?key=API_KEY

回答：

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "location": {
        "latitude": 41.652805199999996,
        "longitude": -83.5378674
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "bounds": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "formattedAddress": "Toledo, OH, USA",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM",
      "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM",
      "location": {
        "latitude": 39.8628296,
        "longitude": -4.0273067
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "bounds": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "formattedAddress": "Toledo, España",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "administrative_area_level_4",
            "political"
          ],
          "languageCode": "es"
        },
        ...
      ],
      "types": [
        "administrative_area_level_4",
        "political"
      ]
    },
    ...
  ]
}

如果地理编码请求中包含 regionCode=es（西班牙），则“托莱多”的地理编码只会返回西班牙的结果：

https://geocode.googleapis.com/v4/geocode/address/Toledo?regionCode=es&key=API_KEY