الأسئلة الشائعة عن الترميز الجغرافي
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتناول هذه الأسئلة الشائعة أسئلة متعلّقة بـ Geocoding API.
يمكنك الرجوع إلى الأسئلة الشائعة حول "منصة خرائط Google" للاطّلاع على الأسئلة
الشائعة حول "منصة خرائط Google". اطّلِع أيضًا على
أفضل الممارسات عند ترميز العناوين جغرافيًا.
تحديد المشاكل وحلّها
تحديد المشاكل وحلّها
-
أتلقّى المزيد من طلبات البحث التي تعرض ZERO_RESULTS باستخدام المعرّف الجغرافي. ما هي المشكلة؟
-
في المعرّف الجغرافي، تكون طلبات البحث المُبهمة وغير المكتملة وغير المنسَّقة جيدًا، مثل
العناوين المكتوبة بشكلٍ خاطئ أو غير موجودة، أكثر عرضة لعرض ZERO_RESULTS.
إذا تعذّر العثور على العنوان، يُفضَّل استخدام ZERO_RESULTS بدلاً من نتيجة
جزئية (مثل عرض الضاحية فقط بدلاً من العنوان).
إذا كان تطبيقك يتعامل مع عناوين يدخلها المستخدم، قد تؤدي ميزة
الإكمال التلقائي للأماكن
في Places API إلى تحقيق نتائج ذات جودة أفضل.
تتيح ميزة "الإكمال التلقائي للأماكن" للمستخدمين الاختيار من بين مجموعة من النتائج استنادًا إلى ما
كتبوه، ما يتيح لهم الاختيار بين النتائج التي تحمل أسماء مشابهة،
وتعديل طلب البحث إذا أخطأوا في كتابة عنوان.
إذا كان لديك تطبيق يتعامل مع طلبات بحث غامضة أو غير مكتملة أو طلبات بحث
قد تحتوي على أخطاء، ننصحك باستخدام ميزة
الإكمال التلقائي للأماكن
في Places API بدلاً من أداة الترميز الجغرافي للعنوان المرسَل
المتوفّرة في Geocoding API. لمعرفة المزيد من التفاصيل، يُرجى الاطّلاع على مقالة
أفضل الممارسات عند الترميز الجغرافي للعناوين ومقالة
الترميز الجغرافي للعناوين في مشاركة مدوّنة Google Maps APIs.
-
أحتاج إلى ردود سريعة، وبرنامج ترميز المواقع الجغرافية بطيء جدًا لتطبيقي. ما هي الأدوات التي يمكنني
استخدامها للحصول على ردود أسرع؟
-
ننصحك بأن تستخدم التطبيقات التي تستجيب لإدخال المستخدمين، وبالتالي تكون شديدة حساسية
لوقت الاستجابة، ميزة الإكمال التلقائي للأماكن
في Places API (متوفّرة أيضًا في
JavaScript أو
Android أو
iOS) بدلاً من ترميز العناوين الجغرافية.
تم تحسين ميزة "الإكمال التلقائي للأماكن" لاستخدامها بشكل تفاعلي، وبالتالي يكون وقت استجابتها منخفضًا جدًا.
تم تحسين ترميز العناوين الجغرافي في Geocoding API للاستخدام مع
العناوين الكاملة وغير الغامضة والمُنسَّقة جيدًا، مثل عناوين التسليم التي يتم إدخالها في
النماذج على الإنترنت، وبالتالي يكون وقت استجابة هذه الواجهة أطول من وقت استجابة خدمة "الإكمال التلقائي للأماكن". يتمتع المعرّف الجغرافي للعنوان المُرسَل
بتغطية أكبر وجودة نتائج أفضل، ولكن مع وقت استجابة أعلى إلى حدٍ ما.
-
كيف يمكنني تقليل وقت الاستجابة في Directions API (الإصدار القديم) و
Distance Matrix API (الإصدار القديم)؟
-
بدلاً من العناوين، استخدِم معرّفات الأماكن لتحديد نقاط الطريق والنقطة الأصلية والوجهة. يمكن الحصول على أرقام تعريف الأماكن على أفضل وجه من ميزة
الإكمال التلقائي للأماكن
في Places API أو
مكتبة الأماكن في
Maps JavaScript API. اطّلِع أيضًا على المعلومات حول خيار
placeIdOnly الذي يمكن استخدامه لتقليل تكلفة
ميزة "الإكمال التلقائي للأماكن".
عند إجراء طلب بحث في واجهة برمجة التطبيقات Directions API (القديمة) أو Distance Matrix API (القديمة)
باستخدام سلسلة عنوان بدلاً من معرّف مكان أو إحداثيات خط الطول والعرض، يتم استخدام البنية الأساسية
نفسها المستخدَمة في واجهة برمجة التطبيقات Geocoding API لتحويل هذا العنوان إلى
معرّف مكان قبل احتساب الاتجاهات. إنّ ميزة "الإكمال التلقائي للأماكن" أسرع من ترميز العنوان جغرافيًا. بالنسبة إلى التطبيقات التي تستخدم واجهة برمجة التطبيقات Directions API (القديمة) أو
واجهة برمجة التطبيقات Distance Matrix API (القديمة) في الحالات الحسّاسة للغاية لوقت الاستجابة، مثل
الاستجابة لإدخال المستخدم، ننصحك باستخدام ميزة "الإكمال التلقائي للأماكن" للحصول على معرّفات الأماكن
التي تتوافق مع هذه العناوين، ويجب تمرير معرّفات الأماكن إلى
Directions API (القديمة) أو Distance Matrix API (القديمة).
ويؤدي هذا النهج إلى تقليل وقت الاستجابة بشكل كبير. يمكنك الاطّلاع على مستنداتنا للحصول على
مثال على كيفية استخدام ميزة "الإكمال التلقائي للأماكن" مع الاتجاهات.
-
كيف يمكنني الإبلاغ عن أخطاء في أداة ترميز المواقع الجغرافية؟
-
إذا كان لديك أي
تقارير أخطاء أو
طلبات ميزات لخدمة ترميز المواقع الجغرافية للعنوان، يُرجى إبلاغنا بها باستخدام
أداة تتبُّع المشاكل المتاحة للجميع.
-
لا يقدّم محوِّل الرموز الجغرافية نتائج جيدة لحالة الاستخدام التي أواجهها. ما هي المساعدة المتاحة؟
-
يُرجى إعلامنا باستخدام
نظام تتبُّع المشاكل العلني من خلال مشاركة بعض طلبات البحث المحدّدة، لنتمكّن من التحقيق في
ما إذا كانت هناك أي أخطاء أو مشاكل نظامية تتسبّب في حدوث مشاكل في جودة النتائج، أو ما إذا كانت هناك أي تغييرات يمكننا إجراؤها على
دليل أفضل الممارسات
لمساعدة المطوّرين في الحصول على نتائج أفضل.
-
كيف يمكنني الحصول على أفضل النتائج باستخدام أداة ترميز المواقع الجغرافية باستخدام فلترة المكوّنات؟
-
في المعرّف الجغرافي، تفرض
فلترة المكوّنات قيود postal_code و
country فقط. توضّح الأمثلة التالية أفضل طريقة لاستخدام ميزة
فلترة المكوّنات، استنادًا إلى النتائج التي تحتاج إليها. في نماذج عناوين URL للطلبات، احرص على
استبدال YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات الفعلي.
- لحصر الرموز البريدية ببلد معيّن، احرص على تحديد قيود البلد
باستخدام رمز البلد ISO 3166-2.
على سبيل المثال:
components=country:CH|postal_code:8000 تعرِض "8000 زيورخ، سويسرا".
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 لأجل
توجيه نتائج الموقع الجغرافي، يتم إنشاء استجابة تتضمّن عدة مدن
في الولايات المتحدة الأمريكية باسم "مدريد".
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 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 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 ```"]]
