对地址进行地理编码

欧洲经济区 (EEA) 开发者

地理编码会将地址转换为地图上的位置。 对地址进行地理编码时，响应中会包含：

地理编码请求

地理编码请求是 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 near Dallas, Texas"
具有多种解读的模糊查询 "Charger drop-off"
不再使用的历史名称 "Middlesex United Kingdom"
非地理空间元素或意图 "How many boats are in Ventura Harbor?"
非官方名称或虚名 "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 搭配使用，用于正向地理编码。

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

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

地理编码响应

地理编码会返回一个 GeocodeAddressResponse 对象，其中包含results数组，该数组由 GeocodeResult 对象组成。每个 GeocodeResult 对象代表一个地点。

Geocoding API 响应在 GeocodeResult 中的两个主要位置包含 types 数组：

  1. GeocodeResult.types：此数组表示结果的总体类型。可能的值来自地点类型（新）页面上的表 A 和表 B。
  2. GeocodeResult.addressComponents[].types：每个地址组成部分都有一个 types 数组，表示该地址特定部分的类型。 这些值来自地址类型和地址组成部分类型表（位于地点类型（新）页面上）。

完整的 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。
    • A 混合代码 是至少包含 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 参数定义了此边界框的西南角和东北角的经纬度坐标。

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

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"
      ]
    },
    ...
  ]
}

对“Toledo”的地理编码请求（其中 regionCode=es（西班牙））只会返回西班牙的结果：

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