الطلب
يظهر طلب 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في عنوان URL ويتم ترميز المسافات إلى%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: رمز المنطقة، المحدّد كقيمة من حرفَين لنطاق 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
يوضّح هذا الطلب استخدام العلامة 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" عند البحث عن addresses، على الرغم من أنّ المعرِّف الجغرافي قد يعرض عدة نتائج عندما تكون طلبات البحث عن addresses غامضة.
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 ضمن عنصر استجابة ترميز المواقع الجغرافية. يحتوي هذا الحقل على معلومات أكثر تفصيلاً عن أسباب ظهور رمز الحالة المحدّد.
النتائج
عندما يعرض معرّف المواقع الجغرافية النتائج، يضع هذه النتائج ضمن مصفوفة results (JSON). حتى إذا لم يعرض مُشفِّر الموقع الجغرافي أي نتائج (مثلاً إذا لم يكن العنوان متوفّرًا)، سيظلّ
يعرض مصفوفة results فارغة. (تتكون الردود بتنسيق XML من صفر أو أكثر من عناصر
<result>.)
تحتوي النتيجة النموذجية على الحقول التالية:
- يشير صفيف
types[]إلى نوع النتيجة المعروضة. تحتوي هذه المصفوفة على مجموعة من علامات صفرية أو أكثر تحدّد نوع العنصر الذي يتم عرضه في النتيجة. على سبيل المثال، يعرض الرمز الجغرافي لمدينة "القاهرة" "locality" الذي يشير إلى أنّ "القاهرة" هي مدينة، ويعرض أيضًا "political" الذي يشير إلى أنّها كيان سياسي. قد تحتوي المكوّنات على صفيف types فارغ عندما لا تتوفّر أنواع معروفة لمكوّن العنوان هذا. قد تضيف واجهة برمجة التطبيقات قيم أنواع جديدة حسب الحاجة. لمزيد من المعلومات، يُرجى الاطّلاع على أنواع العناوين وعناصرها. 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_components[]، يشير إلى نوع كل جزء من
العنوان. وتشمل الأمثلة رقم الشارع أو البلد. (في ما يلي قائمة كاملة بأنواع.) قد تحتوي العناوين على أنواع متعددة. يمكن اعتبار الأنواع "علامات".
على سبيل المثال، يتم وضع علامة على العديد من المدن باستخدام النوعَين 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" الرئيسي رسميًا. يُرجى العلم أنّ منح الأولوية لن يؤدي إلا إلى تفضيل النتائج لنطاق معيّن. وإذا كانت هناك نتائج أكثر صلة خارج هذا النطاق، قد يتم تضمينها.
على سبيل المثال، يعرض رمز جغرافي لمدينة "تولّدو" هذه النتيجة، لأنّ النطاق التلقائي لواجهة برمجة التطبيقات 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 API، يمكن أن تعرض واجهة برمجة التطبيقات Geocoding API نتائج عناوين محدودة على منطقة معيّنة. يمكنك تحديد القيود باستخدام
فلتر components. يتألّف الفلتر من قائمة ب pairs
component:value مفصولة بفاصلة (|).
تتوافق قيم الفلتر مع طرق تصحيح الأخطاء الإملائية والمطابقة الجزئية نفسها المستخدَمة في طلبات ترميز المواقع الجغرافية الأخرى. إذا عثر برنامج ترميز المواقع الجغرافية على مطابقة جزئية لأحد فلاتر المكونات، سيحتوي الردّ على حقل 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_coderoute - إذا كان الطلب يحتوي على فلاتر مكوّنات متكرّرة، تقيِّم واجهة برمجة التطبيقات تلك الفلاتر على أنّها عملية "و"، وليس "أو".
- تتطابق النتائج مع "خرائط 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"
}