طلب
يتّخذ طلب Geocoding API الشكل التالي:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
حيث يمكن أن تكون outputFormat إحدى القيمتين التاليتين:
- يشير
json(موصى به) إلى الإخراج بتنسيق JavaScript Object Notation (JSON)؛ أو - يشير
xmlإلى الإخراج بتنسيق XML
يجب استخدام HTTPS.
بعض المَعلمات مطلوبة والبعض الآخر اختياري. وكما هو معتاد في عناوين URL، يتم الفصل بين المَعلمات باستخدام رمز العطف اللاتيني (&).
تصف بقية هذه الصفحة الترميز الجغرافي والترميز الجغرافي العكسي بشكل منفصل، لأنّه تتوفّر مَعلمات مختلفة لكل نوع من الطلبات.
مَعلمات الترميز الجغرافي (البحث عن خطوط الطول والعرض)
المَعلمات المطلوبة في طلب الترميز الجغرافي:
- استبدِل
keyبمفتاح واجهة برمجة التطبيقات لتطبيقك. يحدّد هذا المفتاح تطبيقك لأغراض إدارة الحصة. تعرَّف على كيفية الحصول على مفتاح. يجب تحديد
addressأوcomponentsأو كليهما في الطلب:address— عنوان الشارع أو رمز الموقع المفتوح الذي تريد تحويله إلى إحداثيات جغرافية. يجب تحديد العناوين وفقًا للتنسيق الذي تستخدمه خدمة البريد الوطنية في البلد المعني. يجب تجنُّب إضافة عناصر أخرى إلى العنوان، مثل أسماء المؤسسات وأرقام الوحدات أو الأجنحة أو الطوابق. يجب أن تكون عناصر عنوان الشارع مفصولة بمسافات (يتم عرضها هنا كمسافات تم تحويلها إلى ترميز URL إلى%20):address=24%20Sussex%20Drive%20Ottawa%20ON
%2Bويتم تحويل المسافات إلى%20):- الرمز العالمي هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9 هو
849VCWC8%2BR9). - الرمز المركّب هو رمز محلي يتألف من 6 أحرف أو أكثر ويتضمّن موقعًا جغرافيًا
صريحًا (CWC8+R9 Mountain View, CA, USA هو
CWC8%2BR9%20Mountain%20View%20CA%20USA).
- الرمز العالمي هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9 هو
components: فلتر مكوّنات يتضمّن عناصر مفصولة بعلامة الشرطة العمودية (|). يمكن أيضًا استخدام فلتر المكوّنات كمعلَمة اختيارية في حال توفيرaddress. يتألف كل عنصر في فلتر المكوّنات من زوجcomponent:value، ويحظر النتائج تمامًا من أداة الترميز الجغرافي. يمكنك الاطّلاع على مزيد من المعلومات حول فلترة المكوّنات أدناه.
يمكنك الاطّلاع على الأسئلة الشائعة للحصول على إرشادات إضافية.
المَعلمات الاختيارية في طلب الترميز الجغرافي:
bounds: المربّع المحيط بإطار العرض الذي سيتم فيه عرض نتائج الترميز الجغرافي بشكل أكثر بروزًا. ستؤثّر هذه المَعلمة فقط في النتائج التي يعرضها برنامج الترميز الجغرافي، ولن تفرض قيودًا كاملة عليها. (لمزيد من المعلومات، يُرجى الاطّلاع على تحيّز في إطار العرض أدناه).language: هي اللغة التي سيتم عرض النتائج بها.- اطّلِع على قائمة اللغات المتاحة. تُحدّث Google اللغات المتوافقة بشكل متكرر، لذا قد لا تكون هذه القائمة شاملة.
- في حال عدم توفير
language، يحاول برنامج الترميز الجغرافي استخدام اللغة المفضّلة كما هو محدّد في العنوانAccept-Language، أو اللغة الأصلية للنطاق الذي يتم إرسال الطلب منه. - يبذل برنامج الترميز الجغرافي قصارى جهده لتقديم عنوان شارع يمكن قراءته من قِبل المستخدمين والسكان المحليين. لتحقيق هذا الهدف، تعرض الخدمة عناوين الشوارع باللغة المحلية، مع ترجمتها إلى نص يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكوّنات العنوان باللغة نفسها، التي يتم اختيارها من المكوّن الأول.
- إذا لم يتوفّر اسم باللغة المفضّلة، سيستخدم برنامج الترميز الجغرافي أقرب نتيجة مطابقة.
- للغة المفضّلة تأثير بسيط على مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، وعلى ترتيب عرضها. يفسّر برنامج الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في لغة ما ولكن ليس في لغة أخرى. على سبيل المثال، utca وtér هما كلمتان مترادفتان لكلمتَي شارع وميدان على التوالي باللغة الهنغارية.
- استبدِل
regionبرمز المنطقة المحدّد كقيمة من حرفين لنطاق المستوى الأعلى لرمز البلد. ستؤثّر هذه المَعلمة فقط في النتائج التي يعرضها برنامج الترميز الجغرافي، ولن تفرض قيودًا كاملة عليها. (لمزيد من المعلومات، يُرجى الاطّلاع على تفضيل المنطقة أدناه). يمكن أن تؤثّر هذه المَعلمة أيضًا في النتائج استنادًا إلى القانون الساري. components: فلتر مكوّنات يتضمّن عناصر مفصولة بعلامة الشرطة العمودية (|). يكون فلتر المكوّنات مطلوبًا إذا لم يتضمّن الطلبaddress. يتألف كل عنصر في فلتر المكوّنات من زوجcomponent:value، ويحظر النتائج تمامًا من أداة الترميز الجغرافي. يمكنك الاطّلاع على مزيد من المعلومات حول فلترة المكوّنات أدناه.extra_computations: استخدِم هذه المَعلمة لتحديد الميزات الإضافية التالية في الرد:ADDRESS_DESCRIPTORS— اطّلِع على واصفات العناوين لمزيد من التفاصيل.BUILDING_AND_ENTRANCES— يمكنك الاطّلاع على المداخل والمخططات التفصيلية للمباني لمزيد من التفاصيل.
extra_computationsفي الطلب لكل ميزة، على سبيل المثال:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
الردود
يتم عرض استجابات الترميز الجغرافي بالتنسيق المحدّد بواسطة العلامة output
ضمن طلب عنوان URL، أو بتنسيق JSON تلقائيًا.
في هذا المثال، يطلب Geocoding API الحصول على ردّ json
لاستعلام عن العنوان "1600 Amphitheatre Parkway, Mountain View,
CA".
يوضّح هذا الطلب كيفية استخدام العلامة output بتنسيق JSON:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
يوضّح هذا الطلب استخدام العلامة output في ملف XML:
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
اختَر علامات التبويب أدناه للاطّلاع على نماذج استجابات JSON وXML.
JSON
{ "results": [ { "address_components": [ { "long_name": "1600", "short_name": "1600", "types": [ "street_number" ] }, { "long_name": "Amphitheatre Parkway", "short_name": "Amphitheatre Pkwy", "types": [ "route" ] }, { "long_name": "Mountain View", "short_name": "Mountain View", "types": [ "locality", "political" ] }, { "long_name": "Santa Clara County", "short_name": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ] }, { "long_name": "California", "short_name": "CA", "types": [ "administrative_area_level_1", "political" ] }, { "long_name": "United States", "short_name": "US", "types": [ "country", "political" ] }, { "long_name": "94043", "short_name": "94043", "types": [ "postal_code" ] }, { "long_name": "1351", "short_name": "1351", "types": [ "postal_code_suffix" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4222804, "lng": -122.0843428 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4237349802915, "lng": -122.083183169709 }, "southwest": { "lat": 37.4210370197085, "lng": -122.085881130292 } } }, "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8", "plus_code": { "compound_code": "CWC8+W7 Mountain View, CA", "global_code": "849VCWC8+W7" }, "types": [ "street_address" ] } ], "status": "OK" }
يُرجى العِلم أنّ استجابة JSON تحتوي على عنصرَين أساسيَّين:
- يحتوي
"status"على بيانات وصفية حول الطلب. يمكنك الاطّلاع على رموز الحالة أدناه. - يحتوي
"results"على مصفوفة من معلومات العناوين المرمّزة جغرافيًا ومعلومات الأشكال الهندسية.
بشكل عام، يتم عرض إدخال واحد فقط في مصفوفة "results" لعمليات البحث عن العناوين، ولكن قد يعرض برنامج الترميز الجغرافي عدة نتائج عندما تكون طلبات البحث عن العناوين غير واضحة.
XML
<GeocodeResponse> <status>OK</status> <result> <type>street_address</type> <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address> <address_component> <long_name>1600</long_name> <short_name>1600</short_name> <type>street_number</type> </address_component> <address_component> <long_name>Amphitheatre Parkway</long_name> <short_name>Amphitheatre Pkwy</short_name> <type>route</type> </address_component> <address_component> <long_name>Mountain View</long_name> <short_name>Mountain View</short_name> <type>locality</type> <type>political</type> </address_component> <address_component> <long_name>Santa Clara County</long_name> <short_name>Santa Clara County</short_name> <type>administrative_area_level_2</type> <type>political</type> </address_component> <address_component> <long_name>California</long_name> <short_name>CA</short_name> <type>administrative_area_level_1</type> <type>political</type> </address_component> <address_component> <long_name>United States</long_name> <short_name>US</short_name> <type>country</type> <type>political</type> </address_component> <address_component> <long_name>94043</long_name> <short_name>94043</short_name> <type>postal_code</type> </address_component> <geometry> <location> <lat>37.4224428</lat> <lng>-122.0842467</lng> </location> <location_type>ROOFTOP</location_type> <viewport> <southwest> <lat>37.4212648</lat> <lng>-122.0856069</lng> </southwest> <northeast> <lat>37.4239628</lat> <lng>-122.0829089</lng> </northeast> </viewport> </geometry> <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id> <plus_code> <global_code>849VCWC8+X8</global_code> <compound_code>CWC8+X8 Mountain View, CA</compound_code> </plus_code> </result> </GeocodeResponse>
يُرجى العِلم أنّ استجابة XML تتألف من <GeocodeResponse> واحد وعنصرَين من المستوى الأعلى:
- يحتوي
<status>على بيانات وصفية حول الطلب. يمكنك الاطّلاع على رموز الحالة أدناه. - عنصر
<result>واحد أو أكثر، يحتوي كل منها على مجموعة واحدة من معلومات العنوان المرمّز جغرافيًا ومعلومات الشكل الهندسي.
استجابة XML أطول بكثير من استجابة JSON. لهذا السبب، ننصحك باستخدام json كعلامة الإخراج المفضّلة ما لم تتطلّب خدمتك استخدام xml لسبب ما.
بالإضافة إلى ذلك، تتطلّب معالجة شجرات XML بعض الحذر لكي تتم الإشارة إلى العُقد والعناصر المناسبة. يمكنك الاطّلاع على
تحليل XML باستخدام XPath للحصول على بعض أنماط التصميم المقترَحة لمعالجة الإخراج.
- يتم تضمين نتائج XML في عنصر جذر
<GeocodeResponse>. - يحدّد JSON الإدخالات التي تتضمّن عناصر متعددة باستخدام مصفوفات الجمع (
types)، بينما يحدّد XML هذه الإدخالات باستخدام عناصر مفردة متعددة (<type>). - يتم الإشارة إلى العناصر الفارغة من خلال مصفوفات فارغة في JSON، ولكن من خلال عدم توفّر أي عنصر من هذا النوع في XML. في حال عدم توفّر نتائج، سيعرض الردّ مصفوفة
resultsفارغة بتنسيق JSON، ولكن لن يعرض أي عناصر<result>بتنسيق XML، على سبيل المثال.
رموز الحالة
يحتوي الحقل "status" ضمن عنصر استجابة الترميز الجغرافي على حالة الطلب، وقد يتضمّن معلومات تصحيح الأخطاء لمساعدتك في تتبُّع سبب عدم عمل الترميز الجغرافي. قد يحتوي الحقل "status" على القيم التالية:
- تشير
"OK"إلى عدم حدوث أي أخطاء، وإلى أنّه تم تحليل العنوان بنجاح وتم عرض رمز جغرافي واحد على الأقل. - يشير الرمز
"ZERO_RESULTS"إلى أنّه تمّت عملية الترميز الجغرافي بنجاح ولكن لم يتم عرض أي نتائج. قد يحدث ذلك إذا تم تمريرaddressغير موجود إلى أداة الترميز الجغرافي. - يشير
OVER_DAILY_LIMITإلى أي مما يلي:- مفتاح واجهة برمجة التطبيقات غير متوفّر أو غير صالح.
- لم يتم تفعيل الفوترة في حسابك.
- تم تجاوز الحد الأقصى للاستخدام الذي تم فرضه ذاتيًا.
- لم تعُد طريقة الدفع المقدَّمة صالحة (على سبيل المثال، انتهت صلاحية بطاقة ائتمان).
يمكنك الاطّلاع على الأسئلة الشائعة حول "خرائط Google" للتعرّف على كيفية حلّ هذه المشكلة.
- يشير الرمز
"OVER_QUERY_LIMIT"إلى أنّك تجاوزت حصتك. - يشير الرمز
"REQUEST_DENIED"إلى أنّه تم رفض طلبك. - تشير السمة
"INVALID_REQUEST"بشكل عام إلى أنّ طلب البحث (addressأوcomponentsأوlatlng) غير متوفّر. - يشير الرمز
"UNKNOWN_ERROR"إلى أنّه تعذّر معالجة الطلب بسبب حدوث خطأ في الخادم. قد ينجح الطلب إذا أعدت المحاولة.
رسائل الخطأ
عندما يعرض برنامج الترميز الجغرافي رمز حالة غير OK، قد يكون هناك حقل error_message إضافي ضمن عنصر استجابة الترميز الجغرافي. يحتوي هذا الحقل على معلومات أكثر تفصيلاً حول أسباب رمز الحالة المحدّد.
النتائج
عندما يعرض برنامج الترميز الجغرافي نتائج، يضعها ضمن مصفوفة (JSON).results حتى إذا لم تعرض أداة الترميز الجغرافي أي نتائج (مثلما يحدث إذا كان العنوان غير صالح)، ستظل تعرض مصفوفة results فارغة. (تتألف ردود XML من صفر أو أكثر من عناصر <result>).
يحتوي الناتج النموذجي على الحقول التالية:
- يشير الصفيف
types[]إلى نوع النتيجة المعروضة. تحتوي هذه المصفوفة على مجموعة من صفر أو أكثر من العلامات التي تحدّد نوع الميزة التي تم عرضها في النتيجة. على سبيل المثال، يعرض الرمز الجغرافي "القاهرة" القيمة "locality" التي تشير إلى أنّ "القاهرة" هي مدينة، ويعرض أيضًا القيمة "political" التي تشير إلى أنّها كيان سياسي. قد تحتوي المكوّنات على مصفوفة أنواع فارغة عندما لا تتوفّر أنواع معروفة لمكوّن العنوان هذا. قد تضيف واجهة برمجة التطبيقات قيم أنواع جديدة حسب الحاجة. لمزيد من المعلومات، يُرجى الاطّلاع على أنواع العناوين ومكوّناتها. -
formatted_addressهي سلسلة تحتوي على العنوان الذي يمكن قراءته لهذا الموقع الجغرافي.وغالبًا ما يكون هذا العنوان مطابقًا للعنوان البريدي. يُرجى العِلم أنّ بعض البلدان، مثل المملكة المتحدة، لا تسمح بتوزيع العناوين البريدية الصحيحة بسبب القيود المفروضة على الترخيص.
يتألف العنوان المنسّق منطقيًا من مكوّن واحد أو أكثر من مكوّنات العنوان. على سبيل المثال، يتألف العنوان "111 شارع 8، نيويورك، نيويورك" من المكوّنات التالية: "111" (رقم الشارع)، و"شارع 8" (الطريق)، و"نيويورك" (المدينة)، و "نيويورك" (ولاية أمريكية).
لا تحلّل العنوان المنسَّق آليًا. بدلاً من ذلك، عليك استخدام مكوّنات العنوان الفردية التي تتضمّنها استجابة واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسّق.
-
address_components[]هي مصفوفة تحتوي على المكوّنات المنفصلة التي تنطبق على هذا العنوان.يحتوي كل مكوّن من مكونات العنوان عادةً على الحقول التالية:
types[]هي مصفوفة تشير إلى نوع عنصر العنوان. اطّلِع على قائمة الأنواع المتوافقة.-
long_nameهو الوصف النصي الكامل أو اسم مكوّن العنوان كما يعرضه برنامج الترميز الجغرافي. -
short_nameهو اسم نصي مختصر لمكوّن العنوان، إذا كان متاحًا. على سبيل المثال، قد يتضمّن أحد عناصر العنوان الخاص بولاية ألاسكاlong_nameبقيمة "ألاسكا" وshort_nameبقيمة "AK" باستخدام الاختصار البريدي المكوّن من حرفين.
يُرجى ملاحظة الحقائق التالية حول مصفوفة
address_components[]:- قد تحتوي مصفوفة مكوّنات العنوان على مكوّنات أكثر من
formatted_address. - لا تتضمّن المصفوفة بالضرورة جميع الجهات السياسية التي تتضمّن عنوانًا، باستثناء تلك المضمّنة في
formatted_address. لاسترداد جميع الكيانات السياسية التي تتضمّن عنوانًا معيّنًا، عليك استخدام الترميز الجغرافي العكسي، مع تمرير خطوط الطول والعرض الخاصة بالعنوان كمعلَمة للطلب. - لا نضمن أن يظل تنسيق الرد كما هو بين الطلبات. على وجه الخصوص، يختلف عدد
address_componentsاستنادًا إلى العنوان المطلوب، ويمكن أن يتغيّر بمرور الوقت بالنسبة إلى العنوان نفسه. يمكن أن يغيّر أحد المكوّنات موضعه في المصفوفة. يمكن أن يتغيّر نوع المكوّن. قد لا يتضمّن الردّ اللاحق مكوّنًا معيّنًا.
للتعامل مع مصفوفة المكوّنات، عليك تحليل الرد واختيار القيم المناسبة من خلال التعبيرات. اطّلِع على دليل تحليل الردود.
-
postcode_localities[]هي مصفوفة تشير إلى ما يصل إلى 100 منطقة محلية مضمّنة في رمز بريدي. لا يظهر هذا الحقل إلا عندما تكون النتيجة رمزًا بريديًا يحتوي على عدة مواقع جغرافية. - تحتوي
geometryعلى المعلومات التالية:- تحتوي
locationعلى قيمة خط الطول والعرض التي تم ترميزها جغرافيًا. بالنسبة إلى عمليات البحث العادية عن العناوين، يكون هذا الحقل عادةً هو الأهم. تخزِّن
location_typeبيانات إضافية حول الموقع الجغرافي المحدّد. في ما يلي القيم المسموح بها حاليًا:- يشير الرمز
"ROOFTOP"إلى أنّ النتيجة المعروضة هي رمز جغرافي دقيق يتضمّن معلومات موقع جغرافي دقيقة تصل إلى مستوى دقة عنوان الشارع. - يشير
"RANGE_INTERPOLATED"إلى أنّ النتيجة المعروضة تمثّل قيمة تقريبية (عادةً على طريق) تم استيفاؤها بين نقطتَين دقيقتَين (مثل التقاطعات). يتم عرض النتائج المُقحَمة بشكل عام عندما لا تتوفّر الرموز الجغرافية الخاصة بالأسطح لعنوان شارع. - يشير الرمز
"GEOMETRIC_CENTER"إلى أنّ النتيجة المعروضة هي المركز الهندسي لنتيجة، مثل خط متعدد الأضلاع (على سبيل المثال، شارع) أو مضلّع (منطقة). - يشير الرمز
"APPROXIMATE"إلى أنّ النتيجة المعروضة تقريبية.
- يشير الرمز
- يحتوي
viewportعلى إطار العرض المقترَح لعرض النتيجة التي تم إرجاعها، ويتم تحديده كقيمتَين لخط العرض وخط الطول تحدّدان الركنَينsouthwestوnortheastمن المربّع المحيط بإطار العرض. يتم بشكل عام استخدام إطار العرض لتأطير نتيجة عند عرضها للمستخدم. - يمثّل
bounds(يتم عرضه اختياريًا) المربّع المحيط الذي يمكن أن يحتوي بالكامل على النتيجة المعروضة. يُرجى العِلم أنّ هذه الحدود قد لا تتطابق مع إطار العرض المقترَح. (على سبيل المثال، تشمل سان فرانسيسكو جزر فارالون التي تُعدّ جزءًا من المدينة من الناحية الفنية، ولكن من الأفضل عدم عرضها في إطار العرض).
- تحتوي
-
plus_code(يُرجى الاطّلاع على رمز الموقع المفتوح ورموز Plus Codes) هو مرجع مشفّر للموقع الجغرافي، مشتق من إحداثيات خطوط الطول والعرض، ويمثّل مساحة تبلغ 1/8000 من الدرجة في 1/8000 من الدرجة (حوالي 14 مترًا × 14 مترًا عند خط الاستواء) أو أصغر. يمكن استخدام رموز Plus Codes كبديل لعناوين الشوارع في الأماكن التي لا تتوفّر فيها عناوين (حيث لا يتم ترقيم المباني أو تسمية الشوارع). لا تعرض واجهة برمجة التطبيقات دائمًا رموز Plus Codes.عندما تعرض الخدمة رمز Plus Code، يتم تنسيقه كرمز عالمي ورمز مركّب:
-
global_codeهو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9). -
compound_codeهو رمز محلي يتألف من 6 أحرف أو أكثر ويتضمّن موقعًا جغرافيًا محددًا (CWC8+R9، ماونتن فيو، كاليفورنيا، الولايات المتحدة الأمريكية). يُرجى عدم تحليل هذا المحتوى آليًا.
-
-
يشير الرمز
partial_matchإلى أنّ أداة الترميز الجغرافي لم تعرض تطابقًا تامًا مع الطلب الأصلي، ولكنّها تمكّنت من مطابقة جزء من العنوان المطلوب. ننصحك بمراجعة الطلب الأصلي للتأكّد من عدم وجود أخطاء إملائية و/أو عنوان غير مكتمل.تحدث التطابقات الجزئية في أغلب الأحيان لعناوين الشوارع غير المتوفّرة في المنطقة المحلية التي يتم إرسالها في الطلب. قد يتم أيضًا عرض نتائج مطابقة جزئية عندما يتطابق طلب البحث مع موقعَين جغرافيَين أو أكثر في المنطقة نفسها. على سبيل المثال، سيؤدي البحث عن "شارع هيلبار، بريستول، المملكة المتحدة" إلى عرض مطابقة جزئية لكل من شارع هنري وشارع هنريتا. يُرجى العِلم أنّه إذا تضمّن الطلب جزءًا من العنوان مكتوبًا بشكل خاطئ، قد تقترح خدمة الترميز الجغرافي عنوانًا بديلًا. سيتم أيضًا تصنيف الاقتراحات التي يتم عرضها بهذه الطريقة على أنّها تطابق جزئي.
place_idهو معرّف فريد يمكن استخدامه مع واجهات برمجة تطبيقات أخرى من Google. على سبيل المثال، يمكنك استخدامplace_idفي طلب Places API للحصول على تفاصيل نشاط تجاري محلي، مثل رقم الهاتف وساعات العمل ومراجعات المستخدمين وغير ذلك. اطّلِع على نظرة عامة حول معرّف المكان.
أنواع العناوين وأنواع مكونات العناوين
تشير مصفوفة types في الرد إلى نوع العنوان. تشمل أمثلة أنواع العناوين عنوان شارع أو بلدًا أو كيانًا سياسيًا. تشير مصفوفة types في الحقل address_component إلى نوع كل جزء من العنوان. وتشمل الأمثلة رقم الشارع أو البلد.
قد تتضمّن العناوين أنواعًا متعددة. يمكن اعتبار الأنواع "علامات".
على سبيل المثال، يتم تصنيف العديد من المدن باستخدام النوعَين political وlocality.
تتوفّر الأنواع التالية ويتم عرضها في كل من مصفوفة نوع العنوان ومصفوفة نوع عنصر العنوان:
| نوع العنوان | الوصف |
|---|---|
street_address |
تمثّل هذه السمة عنوان الشارع الدقيق. |
route |
طريق مسمّى (مثل "الطريق السريع 101 في الولايات المتحدة") |
intersection |
تقاطع رئيسي، عادةً ما يكون بين طريقَين رئيسيَّين |
political |
تمثّل كيانًا سياسيًا يشير هذا النوع عادةً إلى مضلّع تابع لإحدى الإدارات المدنية. |
country |
تمثّل هذه السمة الكيان السياسي الوطني، وهي عادةً أعلى نوع ترتيب يعرضه برنامج الترميز الجغرافي. |
administrative_area_level_1 |
هي منطقة إدارية من الدرجة الأولى تقع تحت مستوى البلد. داخل الولايات المتحدة، تكون هذه المستويات الإدارية هي الولايات. لا تظهر هذه المستويات الإدارية في بعض البلدان. في معظم الحالات، ستتطابق administrative_area_level_1 الأسماء المختصرة بشكل كبير مع التقسيمات الفرعية لمعيار ISO 3166-2 والقوائم الأخرى المتداولة على نطاق واسع، ولكن لا يمكن ضمان ذلك لأنّ نتائج الترميز الجغرافي تستند إلى مجموعة متنوعة من الإشارات وبيانات الموقع الجغرافي. |
administrative_area_level_2 |
تمثّل هذه السمة كيانًا مدنيًا من الدرجة الثانية أقل من مستوى البلد. داخل الولايات المتحدة، تكون هذه المستويات الإدارية عبارة عن مقاطعات. لا تظهر هذه المستويات الإدارية في بعض البلدان. |
administrative_area_level_3 |
هي كيان مدني من المستوى الثالث يقع دون مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. لا تظهر هذه المستويات الإدارية في بعض البلدان. |
administrative_area_level_4 |
هي كيان مدني من المستوى الرابع أقل من مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. لا تظهر هذه المستويات الإدارية في بعض البلدان. |
administrative_area_level_5 |
هي كيان مدني من المستوى الخامس أدنى من مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. لا تظهر هذه المستويات الإدارية في بعض البلدان. |
administrative_area_level_6 |
كيان مدني من المستوى السادس أقل من مستوى البلد يشير هذا النوع إلى تقسيم مدني ثانوي. لا تظهر هذه المستويات الإدارية في بعض البلدان. |
administrative_area_level_7 |
هي كيان مدني من المستوى السابع أقل من مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. لا تظهر هذه المستويات الإدارية في بعض البلدان. |
colloquial_area |
اسم بديل شائع الاستخدام للكيان. |
locality |
كيان سياسي لمدينة أو بلدة مسجّلة |
sublocality |
هي منطقة إدارية من الدرجة الأولى تقع تحت منطقة محلية. قد تتلقّى بعض المواقع الجغرافية أحد الأنواع الإضافية: من sublocality_level_1 إلى sublocality_level_5. كل مستوى من مستويات المنطقة الفرعية هو كيان مدني. تشير الأرقام الأكبر إلى منطقة جغرافية أصغر. |
neighborhood |
حيّ مُسمّى |
premise |
موقع جغرافي محدّد الاسم، ويكون عادةً مبنى أو مجموعة من المباني لها اسم مشترك. |
subpremise |
تمثّل هذه السمة كيانًا يمكن تحديد عنوانه أسفل مستوى المكان، مثل شقة أو وحدة سكنية أو جناح. |
plus_code |
مرجع مشفّر للموقع الجغرافي، مشتق من خطوط الطول والعرض يمكن استخدام Plus Codes كبديل لعناوين الشوارع في الأماكن التي لا تتوفّر فيها (حيث لا يتم ترقيم المباني أو تسمية الشوارع). لمزيد من التفاصيل، يمكنك الانتقال إلى https://plus.codes. |
postal_code |
الرمز البريدي المستخدَم لتوجيه البريد داخل البلد |
natural_feature |
معلَم طبيعي بارز |
airport |
أحد المطارات |
park |
متنزّه مُسمّى |
point_of_interest |
تمثّل هذه السمة نقطة اهتمام محدّدة الاسم. عادةً ما تكون "نقاط الاهتمام" هذه عبارة عن كيانات محلية بارزة لا يمكن تصنيفها بسهولة ضمن فئة أخرى، مثل "مبنى إمباير ستيت" أو "برج إيفل". |
تشير القائمة الفارغة من الأنواع إلى عدم توفّر أي أنواع معروفة لمكوّن العنوان المحدّد (على سبيل المثال، Lieu-dit في فرنسا).
بالإضافة إلى ما سبق، قد تتضمّن مكوّنات العنوان الأنواع المدرَجة أدناه.
| نوع مكوّن العنوان | الوصف |
|---|---|
floor |
تمثّل هذه السمة طابق المبنى الذي يقع فيه العنوان. |
establishment |
عادةً ما يكون مكانًا لم يتم تصنيفه بعد. |
landmark |
مكان قريب يُستخدم كمرجع للمساعدة في التنقّل |
point_of_interest |
تمثّل هذه السمة نقطة اهتمام محدّدة الاسم. |
parking |
موقف أو مرآب سيارات |
post_box |
صندوق بريد محدّد |
postal_town |
مجموعة من المناطق الجغرافية، مثل locality وsublocality، تُستخدَم لعناوين المراسلة في بعض البلدان. |
room |
تمثّل هذه السمة غرفة في عنوان مبنى. |
street_number |
رقم الشارع الدقيق |
bus_station وtrain_station وtransit_station |
موقع محطة حافلات أو قطارات أو وسائل نقل عام |
الانحياز في إطار العرض
في طلب ترميز جغرافي، يمكنك توجيه خدمة الترميز الجغرافي لتفضيل النتائج ضمن إطار عرض معيّن (يتم التعبير عنه كمربع محيط). يمكنك إجراء ذلك
ضمن عنوان URL للطلب من خلال ضبط المَعلمة bounds.
تحدّد المَعلمة bounds إحداثيات خط العرض/خط الطول
للزوايا الجنوبية الغربية والشمالية الشرقية من هذا المربع المحيط باستخدام حرف التوجيه
(|) لفصل الإحداثيات.
على سبيل المثال، يعرض الرمز الجغرافي الخاص بـ "واشنطن" بشكل عام ولاية واشنطن الأمريكية:
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
الرد:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
ومع ذلك، تؤدي إضافة وسيطة bounds تحدّد مربّعًا محيطًا حول الجزء الشمالي الشرقي من الولايات المتحدة إلى أن تعرض هذه الرموز الجغرافية مدينة واشنطن العاصمة:
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
الرد:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
انحياز المنطقة
في طلب الترميز الجغرافي، يمكنك توجيه خدمة الترميز الجغرافي لعرض نتائج متحيزة لمنطقة معيّنة باستخدام المَعلمة region. تتلقّى هذه المَعلمة وسيطة ccTLD (نطاق المستوى الأعلى لرمز البلد) تحدّد الانحياز إلى منطقة معيّنة. تتطابق معظم رموز ccTLD مع رموز ISO 3166-1، مع بعض الاستثناءات البارزة. على سبيل المثال، رمز نطاق المستوى الأعلى الخاص بالبلد في المملكة المتحدة هو "uk" (.co.uk)، بينما رمز ISO 3166-1 هو "gb" (وهو يشير تقنيًا إلى "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").
يمكن أن تكون نتائج الترميز الجغرافي متحيزة لكل نطاق تم إطلاق تطبيق "خرائط Google" الرئيسي فيه رسميًا. يُرجى العِلم أنّ التحيز يفضّل النتائج الخاصة بنطاق معيّن فقط، ولكن إذا كانت هناك نتائج أكثر صلة خارج هذا النطاق، قد يتم تضمينها.
على سبيل المثال، يعرض الرمز الجغرافي الخاص بـ "توليدو" هذه النتيجة، لأنّه تم ضبط النطاق التلقائي لواجهة برمجة التطبيقات Geocoding API على الولايات المتحدة. الطلب:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
الرد:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
سيؤدي طلب ترميز جغرافي لـ "طليطلة" مع region=es (إسبانيا) إلى عرض المدينة الإسبانية.
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
الرد:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Toledo",
"short_name" : "TO",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
فلترة المكوّنات
في ردّ خدمة Geocoding، يمكن أن تعرض واجهة برمجة التطبيقات Geocoding API نتائج عناوين محصورة في منطقة معيّنة. يمكنك تحديد القيد باستخدام الفلتر components. يتألف الفلتر من قائمة component:value
أزواج مفصولة بعلامة الشرطة العمودية (|). وتتيح قيم الفلتر طرق تصحيح الأخطاء الإملائية والمطابقة الجزئية نفسها التي تتيحها طلبات Geocoding الأخرى. إذا عثر برنامج الترميز الجغرافي على تطابق جزئي لفلتر مكوّن، سيتضمّن الردّ الحقل partial_match.
تشمل components التي يمكن فلترتها ما يلي:
- تتطابق
postal_codeمعpostal_codeوpostal_code_prefix. - تطابق السمة
countryاسم بلد أو رمز بلد مكوّن من حرفَين حسب معيار ISO 3166-1. تتّبع واجهة برمجة التطبيقات معيار ISO لتحديد البلدان، وتعمل الفلترة بشكل أفضل عند استخدام رمز ISO المقابل للبلد.
يمكن استخدام components التالية للتأثير في النتائج، ولكن لن يتم فرضها:
- يمثّل
routeالاسم الطويل أو القصير للمسار. - تتم مطابقة
localityمع النوعينlocalityوsublocality. - يطابق
administrative_areaجميع المستويات.administrative_area
ملاحظات حول فلترة المكوّنات:
- لا تكرّر فلاتر المكوّنات هذه في الطلبات، وإلا ستعرض واجهة برمجة التطبيقات
الخطأ
Invalid_request:country،postal_code،route - إذا كان الطلب يحتوي على فلاتر مكوّنات متكرّرة، تقيّم واجهة برمجة التطبيقات هذه الفلاتر كـ AND، وليس كـ OR.
- تتطابق النتائج مع "خرائط Google" التي تقدّم أحيانًا ردودًا غير متوقّعة
ZERO_RESULTS. قد يؤدي استخدام ميزة "الإكمال التلقائي للأماكن" إلى تقديم نتائج أفضل في بعض حالات الاستخدام. لمزيد من المعلومات، يُرجى الاطّلاع على هذه الأسئلة الشائعة. - بالنسبة إلى كل مكوّن من مكوّنات العنوان، حدِّده في المَعلمة
addressأو في الفلترcomponents، ولكن ليس في كليهما. قد يؤدي تحديد القيم نفسها في كليهما إلى ظهورZERO_RESULTS.
سيؤدي البحث عن الرمز الجغرافي "شارع هاي، هاستينغز" مع components=country:GB إلى عرض نتيجة في هاستينغز، إنجلترا بدلاً من هاستينغز-أون-هدسون، الولايات المتحدة الأمريكية.
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
الرد:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
يؤدي طلب رمز جغرافي للموقع الجغرافي "سانتا كروز" مع components=country:ES
إلى عرض "سانتا كروز دي تينيريفي" في جزر الكناري، إسبانيا.
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
الرد:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "Santa Cruz de Tenerife",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Santa Cruz de Tenerife, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
},
"location" : {
"lat" : 28.4636296,
"lng" : -16.2518467
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
}
},
"place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
لا تعرض فلترة المكوّنات الرد ZERO_RESULTS إلا إذا قدّمت فلاتر تستبعد بعضها البعض.
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
الرد:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
يمكنك إجراء طلبات بحث صالحة بدون مَعلمة العنوان، وذلك باستخدام componentsالفلتر. (عند الترميز الجغرافي لعنوان كامل، تكون المَعلمة address مطلوبة إذا كان الطلب يتضمّن أسماء وأرقام المباني).
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
الرد:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}