الطلب
يظهر طلب 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 ماونتن فيو، كاليفورنيا، الولايات المتحدة هو
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_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" الرئيسي رسميًا. يُرجى العلم أنّ منح الأولوية لن يؤدي إلا إلى تفضيل النتائج لنطاق معيّن. وإذا كانت هناك نتائج أكثر صلة خارج هذا النطاق، قد يتم تضمينها.
على سبيل المثال، يعرض رمز جغرافي لمدينة "تولّدو" هذه النتيجة، لأنّ النطاق التلقائي لواجهة برمجة التطبيقات 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 نتائج عناوين مقتصرة على منطقة معيّنة. يمكنك تحديد القيود
باستخدام الفلتر components. يتألّف الفلتر من قائمة component:value
أزواج مفصولة بفاصلة (|). تتيح قيم الفلتر استخدام طرق correction correction المطابقة الجزئية نفسها التي تتوفّر في طلبات ترميز المواقع الجغرافية الأخرى. إذا عثر partial_matchgeocoder على مطابقة جزئية لأحد فلاتر المكوّنات، سيحتوي الردّ على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"
}