طلب
يتّخذ طلب بيانات من 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: عنوان الشارع أو رمز Plus Code الذي تريد ترميزه جغرافيًا ملاحظة: لا يحلّ الترميز الجغرافي للعنوان إحداثيات خطوط العرض والطول أو السلاسل الأخرى غير المنظَّمة التي لا تمثّل عنوانًا أو رمز Plus Code. لا يتم قبول الطلبات التي تستخدم هذه السلاسل، وقد تؤدي إلى ظهور ردود خطأ أو سلوك غير محدّد. تشمل الأمثلة على طلبات البحث غير المتوافقة ما يلي:
يجب تحديد العناوين وفقًا للتنسيق الذي تستخدمه خدمة البريد الوطنية في البلد المعني. يجب تجنُّب عناصر العنوان الإضافية، مثل أسماء المؤسسات وأرقام الوحدات أو الأجنحة أو الطوابق. يجب الفصل بين عناصر عنوان الشارع بمسافات (تظهر هنا على شكل أحرف تم تخطيها في عنوان URL إلىنوع طلب البحث مثال إحداثيات خط العرض وخط الطول استخدِم عكس الترميز الجغرافي بدلاً من ذلك. "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 بالقرب من دالاس، تكساس" طلبات البحث الغامضة التي تحتمل تفسيرات متعددة "تسليم الشاحن" الأسماء السابقة التي لم تعُد مستخدَمة "Middlesex United Kingdom" عناصر أو نية غير مرتبطة بالموقع الجغرافي "كم عدد القوارب في ميناء فينتورا؟" الأسماء غير الرسمية أو المخصّصة "The Jenga"
"The Helter Skelter"%20):address=24%20Sussex%20Drive%20Ottawa%20ON
%2B، ويتم ترميز المسافات في عنوان URL على النحو التالي:%20):- الرمز العالمي هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9 هو
849VCWC8%2BR9). - compound code هو رمز محلي يتألف من 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أو اللغة الأصلية للنطاق الذي يتم إرسال الطلب منه. - تبذل أداة الترميز الجغرافي قصارى جهدها لتوفير عنوان شارع يمكن قراءته لكل من المستخدم والسكان المحليين. لتحقيق هذا الهدف، تعرض الدالة عناوين الشوارع باللغة المحلية، ويتم تحويلها صوتيًا إلى نص يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. All other addresses are returned in the preferred language. يتم عرض جميع مكوّنات العنوان باللغة نفسها، والتي يتم اختيارها من المكوّن الأول.
- إذا لم يكن الاسم متاحًا باللغة المفضّلة، تستخدم أداة الترميز الجغرافي أقرب نتيجة مطابقة.
- تؤثر اللغة المفضّلة بشكل بسيط في مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، وفي ترتيب عرضها. تفسّر أداة الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في لغة واحدة ولكن ليس في لغة أخرى. على سبيل المثال، utca وtér هما مرادفان لكلمتَي "شارع" و"ميدان" على التوالي باللغة الهنغارية.
-
region: رمز المنطقة، ويتم تحديده كقيمة من حرفَين لنطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD). ستؤثر هذه المَعلمة فقط في النتائج من أداة الترميز الجغرافي، ولن تفرض قيودًا كاملة عليها. (لمزيد من المعلومات، يُرجى الاطّلاع على الانحياز إلى منطقة معيّنة أدناه). ويمكن أن تؤثر هذه المَعلمة أيضًا في النتائج استنادًا إلى القانون الساري. 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".
يوضّح هذا الطلب كيفية استخدام علامة JSON output:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
يوضّح هذا الطلب كيفية استخدام علامة XML output:
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 8th Avenue, New York, NY" من المكوّنات التالية: "111" (رقم الشارع) و"8th Avenue" (الطريق) و"New York" (المدينة) و "NY" (الولاية الأمريكية).
لا تحلّل العنوان المنسَّق آليًا. بدلاً من ذلك، يجب استخدام مكوّنات العنوان الفردية التي يتضمّنها ردّ من واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.
-
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, Mountain View, CA, USA). لا تحلّل هذا المحتوى آليًا.
-
-
تشير القيمة
partial_matchإلى أنّ أداة الترميز الجغرافي لم تعرض مطابقة تامة للطلب الأصلي، على الرغم من أنّها تمكّنت من مطابقة جزء من العنوان المطلوب. قد تحتاج إلى فحص الطلب الأصلي بحثًا عن أخطاء إملائية و/أو عنوان غير مكتمل.تحدث المطابقات الجزئية في أغلب الأحيان لعناوين الشوارع غير الموجودة ضمن المنطقة التي تمررها في الطلب. قد يتم أيضًا عرض المطابقات الجزئية عندما يتطابق طلب مع موقعَين جغرافيَين أو أكثر في المنطقة نفسها. على سبيل المثال، سيؤدي البحث عن "Hillpar St, Bristol, UK" إلى عرض مطابقة جزئية لكل من Henry Street وHenrietta Street. يُرجى العِلم أنّه إذا كان الطلب يتضمّن مكوّن عنوان مكتوبًا بشكل خاطئ، قد تقترح خدمة الترميز الجغرافي عنوانًا بديلاً. سيتم أيضًا وضع علامة على الاقتراحات التي يتم عرضها بهذه الطريقة على أنّها مطابقة جزئية.
place_idهو معرّف فريد يمكن استخدامه مع Google APIs الأخرى. على سبيل المثال، يمكنك استخدامplace_idفي طلب Places API للحصول على تفاصيل عن نشاط تجاري محلي، مثل رقم الهاتف وساعات العمل ومراجعات المستخدمين والمزيد. اطّلِع على نظرة عامة على رقم تعريف المكان.
أنواع العناوين وأنواع مكوّنات العناوين
تشير مصفوفة types في الاستجابة إلى نوع العنوان. وتشمل أمثلة أنواع العناوين عنوان الشارع أو البلد أو الكيان السياسي. تشير مصفوفة types في حقل address_component إلى نوع كل جزء من العنوان. وتشمل الأمثلة رقم الشارع أو البلد.
قد تتضمّن العناوين أنواعًا متعددة. ويمكن اعتبار الأنواع "علامات".
على سبيل المثال، يتم وضع علامة على العديد من المدن باستخدام النوعَين political وlocality.
تتوفّر الأنواع التالية ويتم عرضها في كلّ من مصفوفات نوع العنوان ونوع مكوّن العنوان:
| نوع العنوان | الوصف |
|---|---|
street_address |
عنوان شارع دقيق |
route |
طريق مسمّى (مثل "US 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" الرئيسي رسميًا. يُرجى العِلم أنّ الانحياز يفضّل فقط النتائج لنطاق معيّن، وإذا كانت هناك نتائج أكثر صلة خارج هذا النطاق، قد يتم تضمينها.
على سبيل المثال، يعرض الرمز الجغرافي لـ "Toledo" هذه النتيجة، لأنّ النطاق التلقائي لـ 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"
}
سيؤدي طلب الترميز الجغرافي لـ "Toledo" مع 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
مفصولة بشريط عمودي (|). تتيح قيم الفلتر استخدام الطرق نفسها
لتصحيح الأخطاء الإملائية والمطابقة الجزئية مثل طلبات الترميز الجغرافي الأخرى. إذا عثرت أداة الترميز الجغرافي على تطابق جزئي لفلتر مكوّنات، ستحتوي الاستجابة على حقل partial_match.
تشمل components التي يمكن فلترتها ما يلي:
-
postal_codeيتطابق معpostal_codeوpostal_code_prefix. - تتطابق السمة
countryمع اسم بلد أو رمز بلد مكوّن من حرفَين وفقًا لمعيار ISO 3166-1. تتّبع واجهة برمجة التطبيقات معيار الهيئة الدولية للمواصفات (أيزو) لتحديد البلدان، وتعمل الفلترة بشكل أفضل عند استخدام رمز 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.
يؤدي الترميز الجغرافي لـ "High St, Hastings" مع 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"
}