الطلب
ويكون طلب البيانات من واجهة برمجة التطبيقات Geocoding على النحو التالي:
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
يجب تنسيق رموز الجمع كما هو موضّح هنا (يتم إدراج علامات الجمع التي يتم تجاوز عنوان URL إليها في%2Bويتم إدراج المسافات في أحرف عناوين URL في الحقل%20):- الرمز العالمي هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9 هو
849VCWC8%2BR9). - الرمز المركّب هو عبارة عن رمز محلي مكون من 6 أحرف أو أكثر له موقع جغرافي صريح (CWC8+R9 ماونتن فيو، كاليفورنيا، الولايات المتحدة الأمريكية:
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 تلقائيًا.
في هذا المثال، تطلب واجهة برمجة التطبيقات Geocoding 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
يوضح هذا الطلب استخدام علامة 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[]إلى نوع النتيجة المعروضة. تحتوي هذه الصفيفة على مجموعة مؤلفة من صفر أو أكثر من العلامات التي تحدِّد نوع الميزة التي يتم عرضها في النتيجة. على سبيل المثال، يعرض الرمز الجغرافي لـ "شيكاغو" كلمة "المنطقة المحلية" التي تشير إلى أنّ "شيكاغو" مدينة، ويعرض أيضًا كلمة "سياسي" مما يشير إلى أنها كيان سياسي. قد تحتوي المكونات على مصفوفة أنواع فارغة عندما لا توجد أنواع معروفة لمكون العنوان هذا. قد تضيف واجهة برمجة التطبيقات قيم الأنواع الجديدة حسب الحاجة. لمزيد من المعلومات، يُرجى الاطّلاع على أنواع العناوين ومكوّناتها. formatted_addressهي سلسلة تحتوي على عنوان هذا الموقع الجغرافي ويمكن للمستخدمين قراءته.غالبًا ما يكون هذا العنوان معادلاً للعنوان البريدي. يُرجى العلم أنّ بعض البلدان، مثل المملكة المتحدة، لا تسمح بتوزيع عناوين بريدية صحيحة بسبب القيود المفروضة على التراخيص.
يتكون العنوان المنسَّق منطقيًا من مكوّن عنوان واحد أو أكثر. على سبيل المثال، يتكوّن العنوان "111 شارع السلام، القاهرة"، من العناصر التالية: "111" (رقم الشارع) و"الجادة الثامنة" (المسار) و"نيويورك" (المدينة) و "نيويورك" (الولاية الأمريكية).
لا تحلل العنوان المنسَّق بطريقة آلية. بدلاً من ذلك، عليك استخدام مكوّنات العنوان الفردية التي تتضمّنها استجابة واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.
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(راجِع Open Location Code ورمز Plus Codes) هو مرجع موقع جغرافي مشفّر، مشتق من إحداثيات خط العرض وخط الطول، ويمثل المنطقة: 1/8, 000 درجة من الدرجة وزاوية 1/8, 000 درجة من الدرجة (حوالي 14 متر × 14 متر على خط الاستواء) أو أقل. يمكن استخدام رموز Plus Codes كبديل لعناوين الشوارع في الأماكن التي لا توجد بها العناوين (حيث لا تكون المباني مرقمة أو لا تتم تسمية الشوارع). لا تعرض واجهة برمجة التطبيقات دائمًا رموز المواقع المفتوحة.عندما تعرض الخدمة رمز Plus Codes، يتم تنسيقه كرمز عام ورمز مركب:
global_codeهو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9).- يتكوّن
compound_codeمن 6 أحرف أو أكثر رمز محلي يشمل موقعًا جغرافيًا صريحًا (CWC8+R9، ماونتن فيو، كاليفورنيا، الولايات المتحدة الأمريكية). يجب عدم تحليل هذا المحتوى آليًا.
-
تشير
partial_matchإلى أن أداة الترميز الجغرافي لم تعرض مطابقة تامة للطلب الأصلي، على الرغم من أنها كانت قادرة على مطابقة جزء من العنوان المطلوب. ننصحك بفحص الطلب الأصلي بحثًا عن أي أخطاء إملائية و/أو عنوان غير مكتمل.غالبًا ما تحدث المطابقات الجزئية لعناوين الشوارع التي لا توجد ضمن المنطقة المحلية التي تدخلها في الطلب. وقد يتم أيضًا عرض المطابقات الجزئية عندما يتطابق الطلب مع موقعين أو أكثر في المنطقة المحلية نفسها. على سبيل المثال، ستعرض نتائج البحث "Hillpar St, Bristol, UK" مطابقة جزئية لكل من شارع "Henry Street" و"شارع هنرييتا". لاحظ أنه إذا كان الطلب يتضمن مكون عنوان به خطأ إملائي، فقد تقترح خدمة الترميز الجغرافي عنوانًا بديلاً. سيتم أيضًا تمييز الاقتراحات التي يتم عرضها بهذه الطريقة على أنها مطابقة جزئية.
place_idهو معرّف فريد يمكن استخدامه مع واجهات Google APIs الأخرى. على سبيل المثال، يمكنك استخدامplace_idفي طلب Places API للحصول على تفاصيل حول نشاط تجاري محلي، مثل رقم الهاتف وساعات العمل ومراجعات المستخدمين وغير ذلك. اطّلِع على نظرة عامة على معرّف المكان.
أنواع العناوين وأنواع مكونات العناوين
تشير مصفوفة types[] في النتيجة إلى
نوع العنوان. تشمل أمثلة أنواع العناوين عنوان الشارع أو
البلد أو الكيان السياسي. هناك أيضًا مصفوفة types[] في address_components[] تشير إلى نوع كل جزء من العنوان. وتشمل الأمثلة رقم الشارع أو البلد. (في ما يلي قائمة كاملة
بالأنواع.) قد تشتمل العناوين على أنواع متعددة. يمكن اعتبار الأنواع "علامات".
على سبيل المثال، يتم وضع علامات على العديد من المدن باستخدام النوع political
والنوع locality.
يمكن استخدام الأنواع التالية وعرضها بواسطة رمز الترميز الجغرافي في كل من مصفوفات نوع العنوان ونوع مكوِّن العنوان:
- تشير السمة
street_addressإلى عنوان شارع دقيق. routeتشير إلى مسار يحمل اسمًا (مثل "US 101").- تشير السمة
intersectionإلى تقاطع رئيسي، يتألف عادةً من طريقَين رئيسيَين. - يشير الرمز
politicalإلى كيان سياسي. يشير هذا النوع عادةً إلى مضلّع تابع لبعض الإدارة المدنية. - يشير
countryإلى الكيان السياسي الوطني، ويكون عادةً أعلى نوع طلب يعرضه برنامج ترميز المواقع الجغرافية. - تشير السمة
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إلى مرجع موقع مرمّز، وهو مشتق من خط العرض وخط الطول. يمكن استخدام رموز 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، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) في المملكة المتحدة هو "uk" (.co.uk) في حين أنّ رمز ISO 3166-1 هو "gb"
(من الناحية التقنية لكيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").
يمكن أن تكون نتائج الترميز الجغرافي منحازة لكل نطاق تم فيه إطلاق تطبيق "خرائط Google" الرئيسي رسميًا. ويُرجى العِلم بأنّ الانحياز يفضّل النتائج الخاصة بنطاق معيّن فقط. وفي حال توفّر نتائج أكثر صلة خارج هذا النطاق، قد يتم تضمينها.
على سبيل المثال، يعرض الرمز الجغرافي لـ "Toledo" هذه النتيجة، لأنّه تم ضبط النطاق التلقائي لواجهة برمجة التطبيقات Geocoding API على الولايات المتحدة. الطلب:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
الرد:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
سيؤدي طلب الترميز الجغرافي لـ "Toledo" مع region=es (إسبانيا) إلى عرض المدينة الإسبانية.
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
الرد:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Toledo",
"short_name" : "TO",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
تصفية المكونات
في استجابة الترميز الجغرافي، يمكن لواجهة برمجة تطبيقات الترميز الجغرافي عرض نتائج العنوان المحصورة على منطقة معيّنة. يمكنك تحديد التقييد باستخدام
فلتر 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"
}