سوالات متداول مربوط به ژئوکدینگ
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
این سؤالات متداول سؤالات مختص به API Geocoding را پوشش می دهد. برای سؤالات رایج در همه پلتفرم های نقشه های Google به سؤالات متداول پلتفرم نقشه های Google مراجعه کنید. همچنین به بهترین روش‌ها هنگام کدگذاری آدرس‌ها مراجعه کنید.
عیب یابی
عیب یابی
- من درخواست های بیشتری دریافت می کنم که ZERO_RESULTS را با geocoder برمی گرداند. چه خبر است؟
در geocoder، پرس و جوهای مبهم، ناقص و با قالب بندی بد، مانند آدرس های غلط املایی یا عدم وجود، مستعد تولید ZERO_RESULTS هستند. اگر آدرس پیدا نشد، ZERO_RESULTS به یک نتیجه جزئی ترجیح داده می شود (به عنوان مثال، به جای آدرس، فقط حومه شهر را برگردانید).
اگر برنامه شما با ورودی آدرس ها توسط کاربر سروکار دارد، ویژگی تکمیل خودکار مکان در Places API ممکن است نتایج با کیفیت بهتری ایجاد کند. تکمیل خودکار مکان به کاربران امکان می‌دهد از میان مجموعه‌ای از نتایج بر اساس آنچه تایپ کرده‌اند، انتخاب کنند، که به کاربران امکان می‌دهد از بین نتایج با نام مشابه یکی را انتخاب کنند و در صورت املای اشتباه آدرس، درخواست خود را تنظیم کنند.
اگر برنامه‌ای دارید که با جستارهای مبهم یا ناقص یا جستارهایی که ممکن است حاوی خطا باشند سروکار دارد، توصیه می‌کنیم از ویژگی تکمیل خودکار مکان در Places API به جای ژئوکدگذار فوروارد موجود در Geocoding API استفاده کنید. برای جزئیات بیشتر، به بهترین روش‌ها هنگام کدگذاری آدرس‌ها و کدگذاری جغرافیایی آدرس در پست وبلاگ Google Maps APIs مراجعه کنید.
- من به پاسخ های سریع نیاز دارم و geocoder برای برنامه من بسیار کند است. برای پاسخگویی سریعتر از چه چیزی می توانم استفاده کنم؟
توصیه می‌کنیم برنامه‌هایی که به ورودی کاربر پاسخ می‌دهند، و بنابراین به تأخیر بسیار حساس هستند، از ویژگی تکمیل خودکار مکان در Places API (همچنین در جاوا اسکریپت ، اندروید ، یا iOS موجود است) به‌جای کدگذاری جغرافیایی آدرس استفاده کنند. تکمیل خودکار مکان برای استفاده تعاملی بهینه شده است و بنابراین تأخیر بسیار کمی دارد.
کدگذاری جغرافیایی آدرس در Geocoding API برای استفاده با آدرس‌های کامل، بدون ابهام و قالب‌بندی مناسب، مانند آدرس‌های تحویل وارد شده در فرم‌های آنلاین، بهینه‌سازی شده است و بنابراین تأخیر بیشتری نسبت به تکمیل خودکار مکان دارد. ژئوکدر فوروارد دارای پوشش بیشتر و کیفیت نتیجه بهتر است، اما با تأخیر کمی بالاتر.
- چگونه می توانم تاخیر در Directions API (Legacy) و Distance Matrix API (Legacy) را کاهش دهم؟
به جای آدرس‌ها، از شناسه‌های مکان برای تعیین ایستگاه‌های بین راه، مبدا و مقصد استفاده کنید. شناسه‌های مکان بهتر است از ویژگی تکمیل خودکار مکان در Places API یا کتابخانه مکان‌ها در Maps JavaScript API به دست آیند. همچنین به اطلاعات مربوط به گزینه placeIdOnly مراجعه کنید، که می تواند برای کاهش هزینه تکمیل خودکار مکان استفاده شود.
وقتی Directions API (Legacy) یا Distance Matrix API (Legacy) با یک رشته آدرس به جای شناسه مکان یا latlng پرس و جو می شود، از همان backend API Geocoding برای تبدیل آن آدرس به شناسه مکان قبل از محاسبه مسیرها استفاده می کنند. تکمیل خودکار مکان سریعتر از کدگذاری جغرافیایی آدرس است. برای برنامه‌هایی که از Directions API (Legacy) یا Distance Matrix API (Legacy) در موقعیت‌های بسیار حساس به تأخیر استفاده می‌کنند، مانند پاسخ دادن به ورودی کاربر، توصیه می‌کنیم از Place Autocomplete برای دریافت شناسه مکان‌های مربوط به آن آدرس‌ها استفاده کنید و شناسه مکان‌ها را به Directions API (Legacy) یا DistanceLecyx (Mastery API) منتقل کنید. این رویکرد تأخیر را به طور قابل توجهی کاهش می دهد. برای مثالی از نحوه استفاده از تکمیل خودکار مکان با دستورالعمل‌ها، به مستندات ما مراجعه کنید.
- چگونه اشکالات را در geocoder گزارش کنم؟
اگر گزارش اشکال یا درخواست ویژگی برای سرویس geocoder فوروارد دارید، با استفاده از ردیاب مسائل عمومی به ما اطلاع دهید.
- geocoder نتایج خوبی برای مورد استفاده من ایجاد نمی کند. چه کمکی در دسترس است؟
با استفاده از ردیاب مسائل عمومی، با به اشتراک گذاشتن چند جستار خاص، به ما اطلاع دهید تا بررسی کنیم که آیا اشکال یا مشکلات سیستمی وجود دارد که باعث ایجاد مشکل در کیفیت نتیجه می‌شود، یا تغییراتی وجود دارد که می‌توانیم در راهنمای بهترین شیوه‌ها برای کمک به توسعه‌دهندگان برای دریافت نتایج بهتر ایجاد کنیم.
- چگونه می توانم بهترین نتایج را با geocoder با استفاده از فیلتر کامپوننت بگیرم؟
در geocoder، فیلتر مؤلفه فقط محدودیت‌های postal_code و country را اعمال می‌کند. نمونه‌های زیر نحوه بهترین استفاده از فیلترینگ مؤلفه را، بسته به نتایج مورد نیاز، نشان می‌دهند. در URL های درخواست نمونه، حتماً «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 لزوماً چندین نتیجه را برای پرس و جوهای مبهم نشان نمی دهد. چنین پرسش‌هایی با تکمیل خودکار مکان بهتر پاسخ داده می‌شوند.
مثال ها:
- Geocoding برای
components=country:US|locality:madrid "Madrid, NM 87010, USA" را برمی گرداند اما هیچ یک از شهرهای دیگر ایالات متحده به نام "Madrid" نیستند. https://maps.googleapis.com/maps/api/geocode/json?components=country:US%7Clocality:madrid&key=YOUR_API_KEY
- استفاده از Place Autocomplete برای
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
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[[["\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 ```"]]
