الطلب
ويكون طلب واجهة برمجة التطبيقات للترميز الجغرافي بالشكل التالي:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
حيث قد تكون outputFormat أي من القيم التالية:
- تشير القيمة
json(مُقترَحة) إلى الناتج في ترميز JavaScript Object Notation (JSON). - تشير السمة
xmlإلى المخرجات في XML.
يجب استخدام بروتوكول HTTPS للطلبات التي تستخدم مفتاح واجهة برمجة تطبيقات.
تكون بعض المعلّمات مطلوبة والبعض الآخر اختياري. وكما هو الحال في عناوين URL،
يتم فصل المعلّمات باستخدام حرف العطف (&).
تصف بقية هذه الصفحة الترميز الجغرافي والترميز الجغرافي العكسي بشكل منفصل، بسبب توفّر معلّمات مختلفة لكل نوع طلب.
معلّمات ترميز المواقع الجغرافية (بحث خطوط الطول/العرض)
المعلّمات المطلوبة في طلب الترميز الجغرافي:
address- عنوان الشارع أو رمز Plus Codes الذي تريد ترميزه الجغرافي حدِّد العناوين وفقًا للتنسيق الذي تستخدمه الخدمة البريدية الوطنية في البلد المعني. ويجب تجنُّب عناصر العنوان الإضافية، مثل أسماء الأنشطة التجارية ووحداتها، وأرقام الجناح أو الطوابق. يجب الفصل بين عناصر عنوان الشارع بمسافات (تظهر هنا على شكل أحرف إلغاء عنوان url إلى%20):address=24%20Sussex%20Drive%20Ottawa%20ON
يجب تنسيق رموز Plus Codes كما هو موضّح هنا (يتم تجاهل علامات الإضافة إلى عنوان URL بدلاً من مسافات، ويتم إلغاء رموز المسافة إلى%20):- الرمز العالمي هو رمز منطقة مكوّن من 4 أحرف ورمز محلي يتضمن 6 أحرف أو أكثر (849VCWC8+R9 هو
849VCWC8%2BR9). - الرمز المركَّب هو رمز محلي مكوّن من 6 أحرف أو أكثر يتضمّن
موقعًا جغرافيًا فاضحًا (CWC8+R9 Mountain View, CA, USA)
CWC8%2BR9%20Mountain%20View%20CA%20USA.
%2B
--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 تلقائيًا.
في هذا المثال، تطلب واجهة برمجة التطبيقات Geocode API استجابة json
لطلب بحث عن رقم تعريف المكان "ChIJeRpOeF67j4AR9ydy_PIzPuM". هذا المكان
رقم تعريف المبنى هو 1600 Amphitheatre Parkway, Mountain View, CA.
يوضح هذا الطلب استخدام علامة JSON output:
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
يوضح هذا الطلب استخدام علامة XML output:
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" في كائن الاستجابة Geocode
حالة الطلب، وقد يحتوي على معلومات تصحيح الأخطاء لمساعدتك في تتبُّع سبب عدم عمل
الترميز الجغرافي. قد يحتوي الحقل "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[]إلى نوع النتيجة المعروضة. تحتوي هذه المصفوفة على مجموعة من الصفر أو أكثر من العلامات التي تحدّد نوع الميزة التي يتم عرضها في النتيجة. على سبيل المثال، يُظهر الترميز الجغرافي لـ "شيكاغو" "المنطقة المحلية" التي تشير إلى أن "شيكاغو" مدينة، وتعرض أيضًا "سياسة" التي تشير إلى أنها كيان سياسي. قد تحتوي المكوّنات على مصفوفة أنواع فارغة عندما لا تكون هناك أنواع معروفة لمكوِّن العنوان هذا. وقد تُضيف واجهة برمجة التطبيقات قيم نوع جديدة حسب الحاجة. لمزيد من المعلومات، راجِع أنواع العناوين ومكوّنات العنوان. formatted_addressهي سلسلة تحتوي على عنوان هذا الموقع الجغرافي الذي يمكن للمستخدمين قراءته.غالبًا ما يعادل هذا العنوان العنوان البريدي. لاحِظ أن بعض البلدان، مثل المملكة المتحدة، لا تسمح بتوزيع العناوين البريدية الصحيحة بسبب قيود الترخيص.
يتكون العنوان المنسّق بشكل منطقي من واحد أو أكثر من مكوّنات العنوان. على سبيل المثال، يتألف العنوان "111 شارع 8، نيويورك، نيويورك" من المكوّنات التالية: "111" (رقم الشارع)، و"شارع 8" (المسار) و"نيويورك" (المدينة) و "نيويورك" (ولاية الولايات المتحدة).
لا يمكنك تحليل العنوان الذي تم تنسيقه آليًا. وبدلاً من ذلك، عليك استخدام مكوّنات العنوان الفردي التي تتضمّنها استجابة واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.
address_components[]هي مصفوفة تحتوي على المكوّنات المنفصلة الملائمة لهذا العنوان.يحتوي كل مكوِّن عنوان عادةً على الحقول التالية:
types[]هي مصفوفة تشير إلى type لمكوّن العنوان. اطّلِع على قائمة الأنواع المتوافقة.long_nameهي الوصف النصي الكامل أو اسم مكوّن العنوان كما هو وارد في برنامج Geocoder.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(اطّلِع على رمز الموقع المفتوح ورمز علامة الجمع)، هو مرجع مشفّر للموقع الجغرافي، مشتق من إحداثيات خطوط الطول والعرض، وهو يمثّل منطقة: 1/8000 درجة من الدرجة بمقدار 1/8000 درجة من الدرجة (حوالي 14 متر × 14 متر في خط الاستواء أو أصغر). يمكن استخدام رموز Plus Codes كبديل لعناوين الشوارع في الأماكن التي لا تتوفّر فيها عناوين (حيث لا يتم إدراج أرقام في المباني أو لا تحمل أسماء). ولا تعرض واجهة برمجة التطبيقات دائمًا رموز Plus Codes.عندما تعرض الخدمة رمز Plus Codes، يتم تنسيقه كرمز عام ورمز مركّب:
global_codeهو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9).compound_codeعبارة عن رمز محلي يتألف من 6 أحرف أو أكثر ويتضمّن موقعًا جغرافيًا فاضحًا (CWC8+R9 و Mountain View وCA وUSA). لا يجوز تحليل هذا المحتوى آليًا.
-
تشير السمة
partial_matchإلى أنّ صانع المحتوى لم يعرض مطابقة تامة للطلب الأصلي، على الرغم من أنه تمكن من مطابقة جزء من العنوان المطلوب. وننصحك بفحص الطلب الأصلي بحثًا عن أخطاء إملائية و/أو عنوان غير مكتمل.غالبًا ما تحدث المطابقات الجزئية لعناوين الشوارع التي لا توجد في المنطقة المحلية التي تمرِّر فيها الطلب. يمكن أيضًا عرض المطابقات الجزئية عندما يتطابق الطلب مع موقعَين جغرافيَين أو أكثر في المنطقة المحلية نفسها. على سبيل المثال، ستؤدي عبارة "Hillpar St, Bristol, UK" إلى عرض مطابقة جزئية لكل من شارع "هنري" و"شارع هنريتا". يُرجى العِلم أنّه إذا كان الطلب يتضمّن مكوّن عنوان غير صحيح، قد تقترح خدمة ترميز المواقع الجغرافية عنوانًا بديلاً. سيتم أيضًا وضع علامة على الاقتراحات التي يتم تشغيلها بهذه الطريقة كمطابقة جزئية.
place_idهو معرّف فريد يمكن استخدامه مع واجهات Google API الأخرى. على سبيل المثال، يمكنك استخدام السمةplace_idفي طلب واجهة برمجة تطبيقات الأماكن للحصول على تفاصيل نشاط تجاري محلي، مثل رقم الهاتف وساعات العمل ومراجعات المستخدمين وغير ذلك. اطّلِع على نظرة عامة على رقم تعريف المكان.
أنواع العناوين وأنواع مكوّنات العناوين
تشير الصفيف types[] في النتيجة إلى نوع العنوان. تشمل أمثلة أنواع العناوين عنوان الشارع أو البلد أو الكيان السياسي. هناك أيضًا مصفوفة types[] في
address_components[] تشير إلى نوع كل جزء
من العنوان. وتشمل الأمثلة رقم الشارع أو البلد. (في ما يلي قائمة كاملة بالأنواع). يمكن أن تكون العناوين أنواعًا متعددة. يمكن أن تُعتبر الأنواع "علامات".
على سبيل المثال، تم وضع علامات على العديد من المدن باستخدام النوع political وlocality.
تتوفّر الأنواع التالية ويتم عرضها من خلال أداة الترميز في كل من صفائف نوع العنوان ونوع مكوّن العنوان:
street_addressيشير إلى عنوان شارع دقيق.- تشير القيمة
routeإلى مسار مُسمّى (مثل "US 101"). - تشير السمة
intersectionإلى تقاطع رئيسي، يتألف عادةً من طريقَين رئيسيتَين. - تشير السمة
politicalإلى كيان سياسي. عادةً ما يشير هذا النوع إلى شكل مضلع بعض الإدارة المدنية. - تشير السمة
countryإلى الكيان السياسي الوطني، وعادةً ما تكون أعلى نوع ترتيب يعرضه برنامج ترميز المواقع الجغرافية. - تشير السمة
administrative_area_level_1إلى كيان مدني من المستوى الأول أسفل مستوى البلد. تكون هذه المستويات الإدارية في الولايات المتحدة. ولا تعرض جميع البلدان هذه المستويات الإدارية. في معظم الحالات، تتطابق الأسماء الإدارية_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إلى نقطة اهتمام مُسمّاة. وعادةً ما تكون "نقاط الاهتمام" هذه كيانات محلية بارزة لا تناسب بسهولة فئة أخرى، مثل "مبنى إمباير ستيت" أو "برج إيفل".
وتشير القائمة الفارغة بالأنواع إلى عدم توفّر أنواع معروفة لمكوّن العنوان المحدّد، على سبيل المثال "ليو أودي" في فرنسا.
بالإضافة إلى ما سبق، قد تتضمّن مكوّنات العنوان الأنواع المذكورة هنا. هذه القائمة ليست شاملة، وتخضع للتغيير.
- يشير
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" هذه النتيجة، لأنّ النطاق التلقائي لواجهة برمجة تطبيقات ترميز المواقع الجغرافية مضبوط على الولايات المتحدة. الطلب:
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"
}
فلترة المكوّنات
في ردّ ترميز المواقع الجغرافية، يمكن لواجهة برمجة تطبيقات ترميز المواقع الجغرافية عرض نتائج عناوين تقتصر على منطقة معيّنة. يمكنك تحديد التقييد باستخدام
فلتر 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_coderoute - وإذا كان الطلب يحتوي على فلاتر مكوّنات متكرّرة، تقيّم واجهة برمجة التطبيقات هذه الفلاتر باعتبارها عامل تشغيل AND.
- تتوافق النتائج مع "خرائط 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"
}