الطلب
ويكون طلب واجهة برمجة التطبيقات للترميز الجغرافي بالصيغة التالية:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
حيث قد تكون السمة outputFormat إحدى القيمتَين التاليتَين:
- تشير القيمة
json(الخيار الذي يُنصح به) إلى الإخراج بتنسيق JavaScript Object Notation (JSON). - تشير السمة
xmlإلى أنّ المحتوى بتنسيق XML.
يجب استخدام HTTPS للطلبات التي تستخدم مفتاح واجهة برمجة التطبيقات.
تكون بعض المَعلمات مطلوبة وبعضها اختياريًا. وكما هو الحال في عناوين URL،
يتم فصل المعلمات باستخدام حرف العطف (&).
يصف الجزء المتبقي من هذه الصفحة الترميز الجغرافي والترميز الجغرافي العكسي بشكل منفصل، لأنه تتوفر معلَمات مختلفة لكل نوع من الطلبات.
معلمات الترميز الجغرافي (البحث عن خطوط الطول/العرض)
المَعلمات المطلوبة في طلب الترميز الجغرافي:
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).
--OR--
components: فلتر مكوّن يحتوي على عناصر تفصل بينها شرطة رأسية (|). ويتم أيضًا قبول فلتر المكوّنات كمَعلمة اختيارية في حال توفيرaddress. يتكون كل عنصر في فلتر المكونات من زوجcomponent:value، ويحظر النتائج تمامًا من أداة الترميز الجغرافي. يمكنك الاطّلاع على مزيد من المعلومات حول فلترة المكوّنات أدناه.- الرمز العام هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (القيمة 849VCWC8+R9 هي
key— مفتاح واجهة برمجة التطبيقات لتطبيقك ويحدِّد هذا المفتاح تطبيقك لأغراض إدارة الحصة. تعرَّف على كيفية الحصول على مفتاح.
يُرجى الرجوع إلى الأسئلة الشائعة للحصول على إرشادات إضافية.
المَعلمات الاختيارية في طلب الترميز الجغرافي:
bounds— المربّع المحيط بإطار العرض الذي يؤدي إلى انحياز النتيجة الجغرافية في نتائج البحث بشكل أكثر وضوحًا ولن تؤثر هذه المعلمة إلا في النتائج الواردة من رمز الترميز الجغرافي، ولن تحظرها بشكل كامل. (لمزيد من المعلومات، راجع انحياز إطار العرض أدناه).language: اللغة التي يتم عرض النتائج بها- اطّلِع على قائمة اللغات المتاحة. يعدّل Google عادةً اللغات المعتمَدة، لذا قد لا تكون هذه القائمة شاملة.
- إذا لم يتم تقديم
language، يحاول أداة الترميز الجغرافي استخدام اللغة المفضّلة كما هو محدّد في العنوانAccept-Language، أو اللغة الأصلية للنطاق الذي يتم إرسال الطلب منه. - يبذل جهاز الترميز الجغرافي قصارى جهده لتوفير عنوان شارع سهل القراءة للمستخدم والسكان المحليين. ولتحقيق هذا الهدف، تعرض الأداة عناوين الشوارع باللغة المحلية، ويتم تحويلها صوتيًا إلى نص يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. يتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكوّنات العنوان باللغة نفسها التي يتم اختيارها من المكوّن الأول.
- وإذا كان الاسم غير متاح باللغة المفضلة، يستخدم رمز الموقع الجغرافي أقرب تطابق.
- تؤثر اللغة المفضّلة بشكل طفيف في مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، وترتيب عرضها. يفسّر أداة الترميز الجغرافي الاختصارات بشكل مختلف تبعًا للّغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في لغة معيّنة وليس بلغة أخرى. على سبيل المثال، utca وtér مرادفان للشارع والمربّع على التوالي باللغة المجرية.
region: يتم تحديد رمز المنطقة على أنّه قيمة مؤلفة من حرفَين من نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد (ccTLD). ولن تؤثر هذه المعلمة إلا في النتائج الواردة من رمز الترميز الجغرافي، ولن تحظرها بشكل كامل. (لمزيد من المعلومات، راجع انحياز المنطقة أدناه). ويمكن أن تؤثر المَعلمة أيضًا في النتائج استنادًا إلى القانون الساري.components: فلتر المكوّنات يحتوي على عناصر مفصولة بشرطة رأسية (|). يكون فلتر المكوّنات مطلوبًا إذا لم يتضمّن الطلبaddress. يتكون كل عنصر في فلتر المكونات من زوجcomponent:value، ويحظر النتائج تمامًا من أداة الترميز الجغرافي. يمكنك الاطّلاع على مزيد من المعلومات حول فلترة المكوّنات أدناه.
الردود
يتم عرض استجابات الترميز الجغرافي بالتنسيق الذي تشير إليه علامة output ضمن طلب عنوان URL أو بتنسيق JSON تلقائيًا.
في هذا المثال، تطلب واجهة برمجة التطبيقات للترميز الجغرافي الاستجابة json لطلب بحث عن معرّف المكان "ChIJeRpOeF67j4AR9ydy_PIzPuM". رقم التعريف هذا
للمبنى التالي: 1600 Amphitheatre Parkway, Mountain View, CA.
يوضِّح هذا الطلب استخدام علامة output JSON:
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
يوضح هذا الطلب استخدام علامة output بتنسيق XML:
https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&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"
]
}
],
"formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
"geometry": {
"location": {
"lat": 37.4224428,
"lng": -122.0842467
},
"location_type": "ROOFTOP",
"viewport": {
"northeast": {
"lat": 37.4239627802915,
"lng": -122.0829089197085
},
"southwest": {
"lat": 37.4212648197085,
"lng": -122.0856068802915
}
}
},
"place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
"plus_code": {
"compound_code": "CWC8+X8 Mountain View, CA",
"global_code": "849VCWC8+X8"
},
"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 إضافي داخل كائن استجابة الترميز الجغرافي. يحتوي هذا الحقل على معلومات أكثر تفصيلاً
حول الأسباب الكامنة وراء كود الحالة المحدد.
النتائج
عندما يعرض أداة الترميز الجغرافي النتائج، يضعها ضمن مصفوفة results (JSON). حتى إذا لم يعرض الترميز الجغرافي أي نتائج (مثلاً، إذا كان العنوان غير متوفّر)، فإنه لا يزال يعرض مصفوفة results فارغة. (تتكوّن استجابات XML من صفر أو أكثر من عناصر <result>.)
تحتوي النتيجة المعتادة على الحقول التالية:
- وتوضح الصفيفة
types[]type النتيجة المعروضة. يحتوي هذا الصفيف على مجموعة من صفر أو أكثر من العلامات التي تحدد نوع الميزة التي يتم عرضها في النتيجة. على سبيل المثال، يعرض الرمز الجغرافي "شيكاغو" "المنطقة المحلية" التي تشير إلى أنّ "شيكاغو" مدينة، ويعرض أيضًا كلمة "سياسي" مما يشير إلى أنّها كيان سياسي. قد تحتوي المكونات على مصفوفة أنواع فارغة عندما لا توجد أنواع معروفة لمكون العنوان هذا. قد تضيف واجهة برمجة التطبيقات قيم أنواع جديدة حسب الحاجة. وللحصول على مزيد من المعلومات، يُرجى الاطّلاع على أنواع العناوين ومكوّناتها. formatted_addressهي سلسلة تحتوي على العنوان الذي يمكن للإنسان قراءته لهذا الموقع الجغرافي.وغالبًا ما يكون هذا العنوان مساويًا للعنوان البريدي. يُرجى العلم أنّ بعض البلدان، مثل المملكة المتحدة، لا تسمح بتوزيع العناوين البريدية الحقيقية بسبب القيود المفروضة على التراخيص.
يتكون العنوان المنسَّق منطقيًا من مكوّن عنوان واحد أو أكثر. على سبيل المثال، يتكوّن العنوان "111 شارع النيل، القاهرة"، من المكوّنات التالية: "111" (رقم الشارع) و"الجادة 8" (المسار) و"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[]هي مصفوفة تشير إلى جميع المناطق المحلية المضمّنة في رمز بريدي. لا تظهر هذه السمة إلا عندما تكون النتيجة رمزًا بريديًا يتضمّن عدة مناطق محلية. - يحتوي
geometryعلى المعلومات التالية:- يحتوي
locationعلى قيمة خط الطول وخط العرض المرمز جغرافيًا. في عمليات البحث العادية عن العناوين، يكون هذا الحقل عادةً هو الأكثر أهمية. تخزِّن دالة
location_typeبيانات إضافية عن الموقع الجغرافي المحدَّد. في ما يلي القيم المتوافقة حاليًا:- تشير السمة
"ROOFTOP"إلى أنّ النتيجة المعروضة هي رمز جغرافي دقيق ولدينا معلومات دقيقة عن الموقع الجغرافي وصولاً إلى دقة عنوان الشارع. - تشير السمة
"RANGE_INTERPOLATED"إلى أنّ النتيجة المعروضة تعكس تقديرًا تقريبيًا (عادةً على طريق) يقع بين نقطتين دقيقتَين (مثل التقاطعات). بشكل عام، يتم عرض النتائج المدمَجة عندما لا تتوفّر الرموز الجغرافية على الأسطح لعنوان شارع. - تشير السمة
"GEOMETRIC_CENTER"إلى أنّ النتيجة المعروضة هي المركز الهندسي للنتيجة، مثل خط متعدد الخطوط (شارع مثلاً) أو مضلّع (منطقة). - تشير السمة
"APPROXIMATE"إلى أنّ النتيجة المعروضة تقريبية.
- تشير السمة
- يحتوي
viewportعلى إطار العرض المقترَح لعرض النتيجة المعروضة، والمحددة كقيمتَين لخطَي العرض والطول تحددان الزاويةsouthwestوnortheastمن مربع حدود إطار العرض. وبشكل عام، يتم استخدام إطار العرض لتحديد النتيجة عند عرضها للمستخدم. - تخزِّن دالة
bounds(يتم عرضها اختياريًا) مربع الإحاطة الذي يمكن أن يحتوي بالكامل على النتيجة المعروضة. يُرجى العِلم أنّ هذه الحدود قد لا تتطابق مع إطار العرض المقترَح. (على سبيل المثال، تضم مدينة سان فرانسيسكو جزر فارالون، وهي من الناحية الفنية جزءًا من المدينة، ولكن من المحتمل ألا يتم عرضها في إطار العرض).
- يحتوي
-
plus_code(راجِع Open Location Code (رمز الموقع الجغرافي المفتوح) وPlus code) هو مرجع موقع جغرافي مشفّر، مشتق من إحداثيات خطي الطول والعرض، ويمثل منطقة: 1/8000 درجة في 1/8000 درجة (حوالي 14 متر x 14 متر عند خط الاستواء) أو أقل. يمكن استخدام رموز المواقع المفتوحة كبديل لعناوين الشوارع في الأماكن التي لا تتواجد فيها العناوين (حيث لا تكون المباني مرقّمة أو لا تتم تسمية الشوارع). لا تعرض واجهة برمجة التطبيقات دائمًا رموز المواقع المفتوحة.عندما تقوم الخدمة بإرجاع رمز Plus Codes، يتم تنسيقه كرمز عام ورمز مركب:
global_codeهو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9).compound_codeهو رمز محلي مكوّن من 6 أحرف أو أكثر مع موقع جغرافي صريح (CWC8+R9، ماونتن فيو، كاليفورنيا، الولايات المتحدة الأمريكية). لا تحلّل هذا المحتوى آليًا.
-
يشير
partial_matchإلى أن أداة الترميز الجغرافي لم تعرض مطابقة تامة للطلب الأصلي، على الرغم من تمكّنه من مطابقة جزء من العنوان المطلوب. يمكنك فحص الطلب الأصلي بحثًا عن أي أخطاء إملائية و/أو عنوان غير مكتمل.غالبًا ما تحدث المطابقات الجزئية لعناوين الشوارع التي لا توجد داخل المنطقة المحلية التي يتم تمريرها في الطلب. ويمكن أيضًا عرض المطابقات الجزئية عندما يتطابق طلب مع موقعين أو أكثر في المنطقة المحلية نفسها. على سبيل المثال، ستعرض عبارة "Hillpar St, Bristol, UK" مطابقة جزئية لكل من Henry Street وHenrietta Street. لاحظ أنه إذا اشتمل أحد الطلبات على مكون عنوان به خطأ إملائي، فقد تقترح خدمة الترميز الجغرافي عنوانًا بديلاً. سيتم أيضًا تمييز الاقتراحات التي يتم تنفيذها بهذه الطريقة باعتبارها مطابقة جزئية.
place_idهو معرّف فريد يمكن استخدامه مع Google APIs الأخرى. على سبيل المثال، يمكنك استخدامplace_idفي طلب Places API للحصول على تفاصيل حول نشاط تجاري محلي، مثل رقم الهاتف وساعات العمل ومراجعات المستخدمين وغير ذلك. اطّلع على نظرة عامة على معرّف المكان.
أنواع العنوان وأنواع مكوّنات العنوان
تشير الصفيفة types[] في النتيجة إلى نوع العنوان. من أمثلة أنواع العناوين عنوان شارع أو بلدًا أو كيانًا سياسيًا. يتضمّن address_components[] أيضًا مصفوفة types[]، تشير إلى نوع كل جزء من العنوان. وتشمل الأمثلة رقم الشارع أو البلد. (في ما يلي قائمة كاملة
بالأنواع). قد يكون للعناوين أنواع متعددة. يمكن اعتبار الأنواع "علامات".
على سبيل المثال، تتمّ الإشارة إلى العديد من المدن باستخدام النوع political والنوع locality.
يمكن استخدام الأنواع التالية وعرضها من خلال رمز الترميز الجغرافي في كل من مصفوفات نوع العنوان ونوع مكوّن العنوان:
- تشير السمة
street_addressإلى عنوان شارع دقيق. - تشير السمة
routeإلى مسار يحمل اسمًا (مثل "US 101"). - تشير السمة
intersectionإلى تقاطع رئيسي، وعادةً ما يربط بين طريقَين رئيسيتَين. - يشير الرمز
politicalإلى كيان سياسي. يشير هذا النوع عادةً إلى مضلع بعض الإدارة المدنية. - تشير السمة
countryإلى الكيان السياسي الوطني، وهي عادةً أعلى نوع ترتيب يعرضه برنامج Geocoder. - تشير السمة
administrative_area_level_1إلى كيان مدني من الدرجة الأولى أسفل مستوى البلد. وداخل الولايات المتحدة، هذه المستويات الإدارية هي ولايات. ولا تظهر هذه المستويات الإدارية في بعض الدول. في معظم الحالات، تتطابق الأسماء المختصرة admin_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إلى مرجع موقع جغرافي مشفّر، مستمدًا من خط العرض وخط الطول. يمكن استخدام رموز المواقع المفتوحة كبديل لعناوين الشوارع في الأماكن التي لا توجد فيها (حيث لا تكون المباني مرقمة أو لا يتم تحديد أسماء للشوارع). يمكنك الاطّلاع على 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، مع بعض الاستثناءات الملحوظة. على سبيل المثال، يكون نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) للمملكة المتحدة هو "uk" (.co.uk) بينما يكون رمز ISO 3166-1 هو "gb"
(من الناحية الفنية لجهة "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").
يمكن انحياز نتائج الترميز الجغرافي لكل نطاق يتم فيه إطلاق تطبيق "خرائط Google" الرئيسي رسميًا. ويُرجى العِلم بأنّ انحياز النتائج يفضِّل فقط نطاقًا محددًا، وإذا كانت هناك نتائج أكثر صلة خارج هذا النطاق، قد يتم تضمينها.
على سبيل المثال، يعرض الرمز الجغرافي لـ "Toledo" هذه النتيجة، إذ يتم ضبط النطاق التلقائي لواجهة برمجة التطبيقات GeoCODE على الولايات المتحدة. الطلب:
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"
}
فلترة المكوّنات
في استجابة الترميز الجغرافي، يمكن لواجهة برمجة التطبيقات Geocode API عرض نتائج عنوان تقتصر على منطقة معيّنة. يمكنك تحديد التقييد باستخدام فلتر components. ويتكوّن الفلتر من قائمة من
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_codeأوroute. - إذا كان الطلب يحتوي على فلاتر مكوّنات متكرّرة، ستقيّم واجهة برمجة التطبيقات هذه الفلاتر على شكل حرف AND وليس حرف OR.
- تتوافق النتائج مع "خرائط Google"، ما قد يؤدي في بعض الأحيان إلى ظهور
ردود غير متوقّعة باستخدام
ZERO_RESULTS. وقد يؤدي استخدام ميزة "الإكمال التلقائي" للأماكن إلى تقديم نتائج أفضل في بعض حالات الاستخدام. للاطّلاع على مزيد من المعلومات، يُرجى مراجعة هذه الأسئلة الشائعة. - بالنسبة إلى كل مكوّن عنوان، حدِّده في المَعلمة
addressأو في فلترcomponentsولكن ليس في كليهما. وقد يؤدي تحديد القيم نفسها في كلتا الصفحتين إلى عرض الخطأZERO_RESULTS.
يعرض الرمز الجغرافي لـ "هاي ستينغز، هاستينغز" مع components=country:GB
النتيجة في مدينة هاستينغز بإنجلترا بدلاً من النتيجة في هاستينغز أون هدسون بالولايات المتحدة الأمريكية.
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
الرد:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
إنّ طلب الرمز الجغرافي لمنطقة "سانتا كروز" مع components=country:ES
يؤدي إلى إرجاع سانتا كروز دي تينيريفي في جزر الكناري في إسبانيا.
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
الرد:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "Santa Cruz de Tenerife",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Santa Cruz de Tenerife, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
},
"location" : {
"lat" : 28.4636296,
"lng" : -16.2518467
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
}
},
"place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
لا تعرض تصفية المكونات استجابة ZERO_RESULTS
إلا إذا وفرت فلاتر تستبعد بعضها البعض.
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
الرد:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
يمكنك إنشاء طلبات بحث صالحة بدون مَعلمة العنوان، وذلك باستخدام فلتر
components. (عند الترميز الجغرافي لعنوان كامل، تكون المعلمة address مطلوبة إذا كان الطلب يحتوي على أسماء المباني وأرقامها).
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
الرد:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}