地理编码常见问题解答
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
本常见问题解答涵盖了与 Geocoding API 相关的特定问题。
对于涉及整体 Google Maps Platform 的共性问题，请参阅 Google Maps Platform 常见问题解答。另请参阅对地址进行地理编码的最佳实践。
问题排查
问题排查
-
我收到的更多查询在使用地理编码器时会返回 ZERO_RESULTS。这是怎么回事？
-
在地理编码器中，含糊不清、不完整和格式错误的查询（例如拼写错误或不存在的地址）往往会产生 ZERO_RESULTS。
如果找不到地址，请使用 ZERO_RESULTS，而不是部分结果（例如仅返回郊区，而不是地址）。
如果您的应用处理用户输入的地址，Places API 中的地点自动补全功能可能会提供质量更高的结果。
借助地点自动补全功能，用户可以根据自己输入的内容从一组结果中进行选择，从而从名称相似的结果中进行选择，并在拼错地址时调整查询。
如果您的应用处理的是模糊不清或不完整的查询，或者可能包含错误的查询，我们建议您使用 Places API 中的地点自动补全功能，而不是 Geocoding API 中提供的正向地理编码器。如需了解详情，请参阅
对地址进行地理编码的最佳实践以及
Google Maps API 博文中的地址地理编码。
-
我需要快速响应，而地理编码器速度太慢，不适合我的应用。我可以使用哪些工具来更快地获得回复？
-
对于响应用户输入且对延迟时间非常敏感的应用，我们建议使用 Places API 中的地点自动补全功能（也适用于 JavaScript、Android 或 iOS），而不是地址地理编码。
地点自动填充针对交互式用途进行了优化，因此延迟时间很短。
Geocoding API 中的地址地理编码经过优化，适用于完整、明确且格式良好的地址（例如输入到在线表单中的送货地址），因此延迟时间比地点自动补全功能更长。正向地理编码器的覆盖率更广，结果质量更好，但延迟时间略长。
-
如何减少 Directions API（旧版）和 Distance Matrix API（旧版）的延迟时间？
-
请使用地点 ID 来指定航点、起点和终点，而不是地址。最好通过 Places API 中的地点自动补全功能或 Maps JavaScript API 中的地点库获取地点 ID。另请参阅
placeIdOnly 选项的相关信息，该选项可用于降低地点自动补全的费用。
当使用地址字符串（而非地点 ID 或经纬度）查询 Directions API（旧版）或 Distance Matrix API（旧版）时，它们会使用与 Geocoding API 相同的后端，在计算路线之前将该地址转换为地点 ID。地点自动补全功能比地址地理编码功能更快捷。对于在对延迟时间极其敏感的情况下（例如响应用户输入）使用 Directions API（旧版）或 Distance Matrix API（旧版）的应用，我们建议您使用地点自动补全功能获取与这些地址对应的地点 ID，并将地点 ID 传递给 Directions API（旧版）或 Distance Matrix API（旧版）。
这种方法可以显著缩短延迟时间。如需查看
有关如何将地点自动补全与路线搭配使用的示例，请参阅我们的文档。
-
如何报告地理编码器中的 bug？
-
如果您对正向地理编码器服务有任何
bug 报告或
功能请求，请使用我们的公开
问题跟踪器告诉我们。
-
地理编码器未针对我的用例生成理想结果。有哪些帮助？
-
请使用我们的公开
问题跟踪器与我们联系，分享一些具体查询，以便我们调查是否存在导致结果质量问题的 bug 或系统性问题，或者我们是否可以对最佳实践指南做出任何更改，以帮助开发者获得更好的结果。
-
如何使用组成部分过滤功能让地理编码器获得最佳结果？
-
在地理编码器中，
组成部分过滤仅会强制执行 postal_code 和 country 限制。以下示例展示了如何根据您需要的结果，最有效地使用组件过滤。在示例请求网址中，请务必将“YOUR_API_KEY”替换为您的实际 API 密钥。
- 如需将邮政编码限制为特定国家/地区，请务必使用 ISO 3166-2 国家/地区代码指定国家/地区限制。
例如：
components=country:CH|postal_code:8000 会返回“8000 Zürich, Switzerland”。
https://maps.googleapis.com/maps/api/geocode/json?components=country:CH%7Cpostal_code:8000&key=YOUR_API_KEY
- 如需将查询限制为特定国家/地区，请务必使用 ISO 3166-2 国家/地区代码指定国家/地区限制。使用国家/地区名称和其他缩写可能不会产生与国家/地区代码相同的结果。
示例：
- 对
components=country:FRA|locality:gallus 进行地理编码会返回德国法兰克福的 Gallus 子行政区。这是因为系统不支持法国的 3 个字母国家/地区代码 (FRA)，因此允许显示任何国家/地区的结果，而法兰克福的结果比法国境内的任何结果都更符合条件。https://maps.googleapis.com/maps/api/geocode/json?components=country:FRA%7Clocality:gallus&key=YOUR_API_KEY
- 对于模糊的查询，Geocoding API 不一定会返回多个结果。地点自动补全功能更适合回答此类查询。
示例：
- 对
components=country:US|locality:madrid 进行地理编码会返回“美国新墨西哥州马德里 87010”，但美国没有任何其他名为“马德里”的城市。https://maps.googleapis.com/maps/api/geocode/json?components=country:US%7Clocality:madrid&key=YOUR_API_KEY
- 针对
input=madrid&components=country:us&types=(regions) 使用地点自动补全功能，并使用 location 和 radius 指定视口以
偏向位置结果，会生成一个响应，其中包含美国多个名为“Madrid”的城市。https://maps.googleapis.com/maps/api/place/autocomplete/json?location=37.386052,-122.083851&radius=10000&input=madrid&components=country:us&types=(regions)&key=YOUR_API_KEY
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-08-31。
[null,null,["最后更新时间 (UTC)：2025-08-31。"],[[["\u003cp\u003eThis FAQ addresses questions about the Geocoding API; for general Google Maps Platform questions, refer to the Google Maps Platform FAQ.\u003c/p\u003e\n"],["\u003cp\u003eFor applications with user input and latency sensitivity, Google recommends using Place Autocomplete instead of address geocoding for better results and speed.\u003c/p\u003e\n"],["\u003cp\u003eTo improve latency with the Directions or Distance Matrix APIs, use place IDs obtained from Place Autocomplete instead of addresses.\u003c/p\u003e\n"],["\u003cp\u003eYou can report bugs or request features for the Geocoding API through the public issue tracker.\u003c/p\u003e\n"],["\u003cp\u003eComponent filtering in the Geocoding API is primarily used to restrict results by country and postal code.\u003c/p\u003e\n"]]],[],null,["This FAQ covers questions specific to the Geocoding API.\nRefer to the [Google Maps Platform FAQ](/maps/faq) for questions\ncommon to all Google Maps Platform. See also\n[Best Practices When Geocoding Addresses](/maps/documentation/geocoding/best-practices).\n\nTroubleshooting\n\n- [I'm getting more queries that return ZERO_RESULTS with the geocoder. What's going on?](#trbl-zero-results)\n- [I need fast responses, and the geocoder is too slow for my application. What can\n I use for faster responses?](#trbl-slow)\n- [How can I mitigate the latency on the Directions API (Legacy) and\n Distance Matrix API (Legacy)?](#trbl-latency)\n- [How do I report bugs in the geocoder?](#trbl-report-bug)\n- [The geocoder isn't producing good results for my use case. What help is available?](#trbl-help)\n- [How do I get the best results with the geocoder using component filtering?](#trbl-component-filtering)\n\nTroubleshooting\n\n\nI'm getting more queries that return ZERO_RESULTS with the geocoder. What's going on?\n\n: In the geocoder, ambiguous, incomplete and badly formatted queries, such as\n misspelled or nonexistent addresses, are prone to produce ZERO_RESULTS.\n If the address cannot be found, ZERO_RESULTS is preferable to a partial\n result (for example returning only the suburb in lieu of an address).\n\n If your application deals with user input of addresses, the\n [Place Autocomplete](/maps/documentation/places/web-service/autocomplete) feature\n in the Places API may produce better quality results.\n Place Autocomplete allows users to select from a set of results based on what\n they've typed, which allows users to choose between similarly named results,\n and to adjust their query if they misspell an address.\n\n If you have an application dealing with ambiguous or incomplete queries or queries\n that may contain errors, we recommend you use the\n [Place Autocomplete](/maps/documentation/places/web-service/autocomplete) feature\n in the Places API rather than the forward geocoder\n available in the Geocoding API. For more details, see\n [Best Practices When Geocoding Addresses](/maps/documentation/geocoding/best-practices) and the\n [Address Geocoding in the Google Maps APIs blog post](https://mapsplatform.google.com/resources/blog/address-geocoding-in-google-maps-apis/).\n\n\nI need fast responses, and the geocoder is too slow for my application. What can\nI use for faster responses?\n\n: We recommend that applications that respond to user input, and therefore are highly\n latency-sensitive, use the [Place Autocomplete](/maps/documentation/places/web-service/autocomplete)\n feature in the Places API (also available in\n [JavaScript](/maps/documentation/javascript/places-autocomplete),\n [Android](/maps/documentation/places/android-sdk/autocomplete), or\n [iOS](/maps/documentation/places/ios-sdk/autocomplete)) rather than address geocoding.\n Place Autocomplete is optimized to be used interactively, and thus has very low latency.\n\n Address geocoding in the Geocoding API is optimized for use with\n complete, unambiguous, well formatted addresses, such as delivery addresses entered into\n online forms, and thus has higher latency than Place Autocomplete. The forward geocoder\n has greater coverage and better result quality, but with somewhat higher latency.\n\n\nHow can I mitigate the latency on the Directions API (Legacy) and\nDistance Matrix API (Legacy)?\n\n: Instead of addresses, use [place IDs](/maps/documentation/places/web-service/place-id) to\n specify waypoints, origin, and destination. Place IDs are best obtained from the\n [Place Autocomplete](/maps/documentation/places/web-service/autocomplete)\n feature in the Places API or the\n [Places library](/maps/documentation/javascript/places-autocomplete) in the\n Maps JavaScript API. See also the information on the\n [`placeIdOnly`](/maps/documentation/javascript/places-autocomplete#placeidonly) option, which can be used to reduce the cost of\n Place Autocomplete.\n\n When the Directions API (Legacy) or Distance Matrix API (Legacy)\n is queried with an address string rather than a place ID or latlng, they use the same\n backend as the Geocoding API to convert that address into a\n place ID prior to calculating directions. Place Autocomplete is faster than address\n geocoding. For applications that use the Directions API (Legacy) or\n Distance Matrix API (Legacy) in highly latency-sensitive situations, such as\n responding to user input, we recommended you use Place Autocomplete to get the place IDs\n corresponding to those addresses, and pass the place IDs to the\n Directions API (Legacy) or Distance Matrix API (Legacy).\n This approach reduces latency significantly. See our documentation for an\n [example of how to use Place Autocomplete with directions](/maps/documentation/javascript/examples/places-autocomplete-directions).\n\n\nHow do I report bugs in the geocoder?\n\n: If you have any\n [bug reports](https://issuetracker.google.com/savedsearches/558483) or\n [feature requests](https://issuetracker.google.com/issues/new?component=188871&template=788905) for the forward geocoder service, let us know using our public\n [issue tracker](https://issuetracker.google.com/issues/new?component=188871&template=788906).\n\n\nThe geocoder isn't producing good results for my use case. What help is available?\n\n: Let us know using our public\n [issue tracker](https://issuetracker.google.com/savedsearches/558483), sharing a few specific queries, so we can investigate to\n see if there are any bugs or systemic issues causing problems with result\n quality, or if there are any changes we can make to the\n [best practices guide](/maps/documentation/geocoding/best-practices)\n to help developers get better results.\n\n\nHow do I get the best results with the geocoder using component filtering?\n\n: In the geocoder, [component filtering](/maps/documentation/geocoding/overview#component-filtering) enforces only `postal_code` and\n `country` restrictions. The following examples illustrate how best to use component\n filtering, depending on the results you need. In the sample request URLs, be sure to\n replace \\`YOUR_API_KEY\\` with your actual API key.\n\n - To restrict postal codes to a specific country, be sure to specify the country restriction using an [ISO 3166-2 country code](https://en.wikipedia.org/wiki/ISO_3166-2). For example: `components=country:CH|postal_code:8000` returns \"8000 Zürich, Switzerland\". \n\n ```scdoc\n https://maps.googleapis.com/maps/api/geocode/json?components=country:CH%7Cpostal_code:8000&key=YOUR_API_KEY\n ```\n - To restrict queries to a specific country, be sure to specify the country restriction using an [ISO 3166-2 country code](https://en.wikipedia.org/wiki/ISO_3166-2). Country names and other abbreviations may not produce the same results as country codes.\n\n Examples:\n - Geocoding for `components=country:FRA|locality:gallus` returns the sublocality of Gallus in Frankfurt am Main, Germany. This is because the 3-letter country code for France (FRA) isn't supported, thus results in any country are allowed and the result in Frankfurt is a better fit than anything in France. \n\n ```scdoc\n https://maps.googleapis.com/maps/api/geocode/json?components=country:FRA%7Clocality:gallus&key=YOUR_API_KEY\n ```\n - Geocoding API won't necessarily return multiple results for ambiguous queries. Such queries are better answered by the Place Autocomplete. Examples:\n\n - Geocoding for `components=country:US|locality:madrid` returns \"Madrid, NM 87010, USA\" but none of the other cities in the USA named \"Madrid\". \n\n ```scdoc\n https://maps.googleapis.com/maps/api/geocode/json?components=country:US%7Clocality:madrid&key=YOUR_API_KEY\n ```\n - Using Place Autocomplete for `input=madrid&components=country:us&types=(regions)`, and also specifying a viewport using `location` and `radius` to [bias the location results](/maps/documentation/places/web-service/autocomplete#location_biasing), generates a response with several cities in the USA named \"Madrid\". \n\n ```carbon\n https://maps.googleapis.com/maps/api/place/autocomplete/json?location=37.386052,-122.083851&radius=10000&input=madrid&components=country:us&types=(regions)&key=YOUR_API_KEY\n ```"]]
