الطلب
يأخذ طلب Geocoding API الشكل التالي:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
حيث يمكن أن يكون outputFormat
أيًّا من القيمتَين التاليتَين:
json
(مُستحسَن) يشير إلى الإخراج بتنسيق JavaScript Object Notation (JSON)- يشير الرمز
xml
إلى الإخراج بتنسيق XML.
يجب استخدام بروتوكول HTTPS.
بعض المَعلمات مطلوبة، وبعضها اختياري. كما هو معتاد في عناوين URL، يتم فصل المَعلمات باستخدام رمز العطف اللاتيني (&
).
توضّح بقية هذه الصفحة الترميز الجغرافي وعكس الترميز الجغرافي بشكل منفصل، لأنّه تتوافر معلَمات مختلفة لكل نوع من الطلبات.
مَعلمات الترميز الجغرافي (البحث عن خطوط الطول والعرض)
المَعلمات المطلوبة في طلب ترميز جغرافي:
address
: عنوان الشارع أو رمز الموقع المفتوح الذي تريد تحويله إلى رمز جغرافي حدِّد العناوين وفقًا للتنسيق الذي تستخدمه الخدمة البريدية الوطنية في البلد المعني. يجب تجنُّب استخدام عناصر العنوان الإضافية، مثل أسماء الأنشطة التجارية وأرقام الوحدات أو الأجنحة أو الطوابق. يجب الفصل بين عناصر عنوان الشارع بفواصل (يتم عرضها هنا على أنّها مشفّرة بترميز URL إلى%20
): يجب تنسيق رموز Plus Codes كما هو موضّح هنا (يتم ترميز علامات الجمع إلى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
، ويحظر تمامًا النتائج من المعرّف الجغرافي. يمكنك الاطّلاع على مزيد من المعلومات عن فلترة المكوّنات أدناه. -
extra_computations
: استخدِم هذه المَعلمة لتحديد الميزات الإضافية التالية في الاستجابة:ADDRESS_DESCRIPTORS
— اطّلِع على موصّفات العناوين للحصول على مزيد من التفاصيل.BUILDING_AND_ENTRANCES
— اطّلِع على مخططات المداخل والمباني لمعرفة المزيد من التفاصيل.
extra_computations
في طلب كل ميزة، على سبيل المثال:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
الردود
يتم عرض ردود ترميز المواقع الجغرافية بالتنسيق الذي يشير إليه العلامة output
ضمن طلب عنوان URL، أو بتنسيق JSON تلقائيًا.
في هذا المثال، تطلب Geocoding API json
استجابة لطلب بحث عن العنوان "1600 Amphitheatre Parkway, Mountain View
CA".
يوضّح هذا الطلب استخدام علامة JSON output
:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
يوضّح هذا الطلب استخدام العلامة output
في ملف XML:
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
اختَر علامات التبويب أدناه للاطّلاع على نماذج الردود بتنسيقَي JSON وXML.
JSON
{ "results": [ { "address_components": [ { "long_name": "1600", "short_name": "1600", "types": [ "street_number" ] }, { "long_name": "Amphitheatre Parkway", "short_name": "Amphitheatre Pkwy", "types": [ "route" ] }, { "long_name": "Mountain View", "short_name": "Mountain View", "types": [ "locality", "political" ] }, { "long_name": "Santa Clara County", "short_name": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ] }, { "long_name": "California", "short_name": "CA", "types": [ "administrative_area_level_1", "political" ] }, { "long_name": "United States", "short_name": "US", "types": [ "country", "political" ] }, { "long_name": "94043", "short_name": "94043", "types": [ "postal_code" ] }, { "long_name": "1351", "short_name": "1351", "types": [ "postal_code_suffix" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4222804, "lng": -122.0843428 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4237349802915, "lng": -122.083183169709 }, "southwest": { "lat": 37.4210370197085, "lng": -122.085881130292 } } }, "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8", "plus_code": { "compound_code": "CWC8+W7 Mountain View, CA", "global_code": "849VCWC8+W7" }, "types": [ "street_address" ] } ], "status": "OK" }
تجدر الإشارة إلى أنّ استجابة JSON تحتوي على عنصرَين أساسيَين:
- يحتوي
"status"
على بيانات وصفية عن الطلب. يمكنك الاطّلاع على رموز الحالة أدناه. - يحتوي
"results"
على صفيف من معلومات العناوين الترميز الجغرافي ومعلومات الشكل الهندسي.
بشكل عام، يتم عرض إدخال واحد فقط في صفيف "results"
عند البحث عن addresses، على الرغم من أنّ المعرِّف الجغرافي قد يعرض عدة نتائج عندما تكون طلبات البحث عن addresses غامضة.
XML
<GeocodeResponse> <status>OK</status> <result> <type>street_address</type> <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address> <address_component> <long_name>1600</long_name> <short_name>1600</short_name> <type>street_number</type> </address_component> <address_component> <long_name>Amphitheatre Parkway</long_name> <short_name>Amphitheatre Pkwy</short_name> <type>route</type> </address_component> <address_component> <long_name>Mountain View</long_name> <short_name>Mountain View</short_name> <type>locality</type> <type>political</type> </address_component> <address_component> <long_name>Santa Clara County</long_name> <short_name>Santa Clara County</short_name> <type>administrative_area_level_2</type> <type>political</type> </address_component> <address_component> <long_name>California</long_name> <short_name>CA</short_name> <type>administrative_area_level_1</type> <type>political</type> </address_component> <address_component> <long_name>United States</long_name> <short_name>US</short_name> <type>country</type> <type>political</type> </address_component> <address_component> <long_name>94043</long_name> <short_name>94043</short_name> <type>postal_code</type> </address_component> <geometry> <location> <lat>37.4224428</lat> <lng>-122.0842467</lng> </location> <location_type>ROOFTOP</location_type> <viewport> <southwest> <lat>37.4212648</lat> <lng>-122.0856069</lng> </southwest> <northeast> <lat>37.4239628</lat> <lng>-122.0829089</lng> </northeast> </viewport> </geometry> <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id> <plus_code> <global_code>849VCWC8+X8</global_code> <compound_code>CWC8+X8 Mountain View, CA</compound_code> </plus_code> </result> </GeocodeResponse>
يُرجى العِلم أنّ استجابة XML تتكوّن من <GeocodeResponse>
واحد وعنصرَين من المستوى الأعلى:
- يحتوي
<status>
على بيانات وصفية عن الطلب. يمكنك الاطّلاع على رموز الحالة أدناه. - صفر أو أكثر من عناصر
<result>
، يحتوي كلّ منها على مجموعة واحدة من معلومات العناوين المُشفَّرة جغرافيًا ومعلومات الأشكال الهندسية
استجابة XML أطول بكثير من استجابة JSON. لهذا السبب، ننصح باستخدام json
كعلامة الإخراج المفضّلة ما لم تكن خدمتك تتطلّب xml
لسبب ما.
بالإضافة إلى ذلك، تتطلّب معالجة أشجار XML بعض الحذر، حتى تتمكّن من الإشارة إلى العقد والعناصر المناسبة. اطّلِع على
تحليل ملف XML باستخدام XPath لمعرفة بعض أنماط التصميم المقترَحة لمعالجة النتائج.
- يتم تضمين نتائج XML في عنصر الجذر
<GeocodeResponse>
. - يشير تنسيق JSON إلى الإدخالات التي تحتوي على عناصر متعددة من خلال استخدام مصفوفات جمع (
types
)، في حين يشير تنسيق XML إلى هذه الإدخالات باستخدام عناصر مفردة متعددة (<type>
). - يتم الإشارة إلى العناصر الفارغة من خلال مصفوفات فارغة في JSON، ولكن من خلال عدم توفّر أي
عنصر مماثل في XML. على سبيل المثال، سيعرض الردّ الذي لا ينتج أي نتائج صفيفًا فارغًا
results
في تنسيق JSON، ولكن بدون عناصر<result>
في تنسيق XML.
رموز الحالة
يحتوي الحقل "status"
ضمن عنصر استجابة ترميز المواقع الجغرافية على حالة
الطلب، وقد يحتوي على معلومات تصحيح الأخطاء لمساعدتك في معرفة سبب عدم نجاح ترميز المواقع الجغرافية. قد يحتوي الحقل "status"
على القيم التالية:
- يشير الرمز
"OK"
إلى عدم حدوث أي أخطاء، فقد تم تحليل العنوان بنجاح وتم عرض رمز جغرافي واحد على الأقل. - يشير الرمز
"ZERO_RESULTS"
إلى أنّه تمّ استخدام الرمز الجغرافي بنجاح ولكنّه لم يعرض أي نتائج. قد يحدث ذلك إذا تم تمريرaddress
غير متوفّر إلى أداة ترميز المواقع الجغرافية. - يشير الرمز
OVER_DAILY_LIMIT
إلى أيّ مما يلي:- مفتاح واجهة برمجة التطبيقات غير متوفّر أو غير صالح.
- لم يتم تفعيل ميزة الفوترة في حسابك.
- تم تجاوز الحد الأقصى للاستخدام الذي فرضته على نفسك.
- لم تعُد طريقة الدفع المقدَّمة صالحة (على سبيل المثال، انتهت صلاحية بطاقة الائتمان).
اطّلِع على الأسئلة الشائعة حول "خرائط Google" للتعرّف على كيفية حلّ هذه المشكلة.
- يشير الرمز
"OVER_QUERY_LIMIT"
إلى أنّك تجاوزت مساحة التخزين المتوفّرة. - يشير الرمز
"REQUEST_DENIED"
إلى أنّه تم رفض طلبك. - يشير الرمز
"INVALID_REQUEST"
بشكل عام إلى أنّ الطلب (address
أوcomponents
أوlatlng
) غير متوفّر. - يشير الرمز
"UNKNOWN_ERROR"
إلى أنّه تعذّر التعامل مع الطلب بسبب خطأ في الخادم. قد ينجح الطلب إذا أعدته.
رسائل الخطأ
عندما يعرض برنامج ترميز المواقع الجغرافية رمز حالة غير OK
، قد يكون هناك حقل إضافي
error_message
ضمن عنصر استجابة ترميز المواقع الجغرافية. يحتوي هذا الحقل على معلومات أكثر تفصيلاً عن أسباب ظهور رمز الحالة المحدّد.
النتائج
عندما يعرض معرّف المواقع الجغرافية النتائج، يضع هذه النتائج ضمن مصفوفة results
(JSON). حتى إذا لم يعرض مُشفِّر الموقع الجغرافي أي نتائج (مثلاً إذا لم يكن العنوان متوفّرًا)، سيظلّ
يعرض مصفوفة results
فارغة. (تتكون الردود بتنسيق XML من صفر أو أكثر من عناصر
<result>
.)
تحتوي النتيجة النموذجية على الحقول التالية:
- يشير صفيف
types[]
إلى نوع النتيجة المعروضة. تحتوي هذه المصفوفة على مجموعة من علامات صفرية أو أكثر تحدّد نوع العنصر الذي يتم عرضه في النتيجة. على سبيل المثال، يعرض الرمز الجغرافي لمدينة "القاهرة" "locality" الذي يشير إلى أنّ "القاهرة" هي مدينة، ويعرض أيضًا "political" الذي يشير إلى أنّها كيان سياسي. قد تحتوي المكوّنات على صفيف types فارغ عندما لا تتوفّر أنواع معروفة لمكوّن العنوان هذا. قد تضيف واجهة برمجة التطبيقات قيم أنواع جديدة حسب الحاجة. لمزيد من المعلومات، يُرجى الاطّلاع على أنواع العناوين وعناصرها. formatted_address
هي سلسلة تحتوي على عنوان هذا الموقع الجغرافي ويمكن لشخص عادي قراءته.وغالبًا ما يكون هذا العنوان مطابقًا للعنوان البريدي. تجدر الإشارة إلى أنّ بعض البلدان، مثل المملكة المتحدة، لا تسمح بتوزيع العناوين البريدية الحقيقية بسبب القيود المفروضة على الترخيص.
يتألّف العنوان المنسَّق منطقيًا من مكوّن عنوان واحد أو أكثر. على سبيل المثال، يتألّف العنوان "111 شارع 8، القاهرة، القاهرة" من المكوّنات التالية: "111" (رقم الشارع)، "شارع 8" (المسار)، و"القاهرة" (المدينة) و"القاهرة" (الولاية).
لا تُحلِّل العنوان المنسَّق آليًا. بدلاً من ذلك، يجب استخدام عناصر العنوان الفردية التي تتضمّنها استجابة واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.
address_components[]
هي مصفوفة تحتوي على المكونات المنفصلة التي تنطبق على هذا العنوان.يحتوي كلّ مكوّن من مكوّنات العنوان عادةً على الحقول التالية:
types[]
هو صفيف يشير إلى نوع مكوّن العنوان. اطّلِع على قائمة الأنواع المتوافقة.long_name
هو الوصف النصي الكامل أو اسم مكوّن العنوان كما يعرضه "محوِّل العناوين الجغرافية".short_name
هو اسم نصي مختصر لمكوّن العنوان ، إن توفّر. على سبيل المثال، قد يحتوي أحد مكوّنات العنوان لولاية ألاسكا علىlong_name
"ألاسكا" وshort_name
"AK" باستخدام الاختصار البريدي المكوّن من حرفَين.
يُرجى ملاحظة الحقائق التالية حول الصفيف
address_components[]
:- قد تحتوي صفيف مكوّنات العنوان على مكوّنات أكثر من
formatted_address
. - لا تتضمّن المصفوفة بالضرورة جميع الكيانات السياسية التي
تحتوي على عنوان، باستثناء تلك المضمّنة في
formatted_address
. لاسترداد جميع الكيانات السياسية التي تحتوي على عنوان معيّن، يجب استخدام الترميز الجغرافي العكسي، مع تمرير خط العرض/خط الطول للعنوان كمَعلمة للطلب. - لا يمكن ضمان أن يظل تنسيق الردّ كما هو بين
الطلبات. على وجه الخصوص، يختلف عدد
address_components
حسب العنوان المطلوب، ويمكن أن يتغيّر بمرور الوقت للعنوان نفسه. يمكن أن يغيّر المكوّن موضعه في الصفيف. يمكن أن يتغيّر نوع المكوّن. قد يكون أحد المكوّنات مفقودًا في ردّ لاحق.
لمعالجة صفيف المكوّنات، عليك تحليل الردّ واختيار القيم المناسبة من خلال التعبيرات. اطّلِع على دليل تحليل الردّ.
postcode_localities[]
هو صفيف يشير إلى ما يصل إلى 100 موقع جغرافي مضمّن في رمز بريدي. لا يظهر هذا الحقل إلا عندما تكون النتيجة رمزًا بريديًا يحتوي على عدة مناطق محلية.- يحتوي
geometry
على المعلومات التالية:- يحتوي الحقل
location
على قيمة خط الطول والعرض المُشفَّرَين جغرافيًا. بالنسبة إلى عمليات البحث العادية عن العنوان، يكون هذا الحقل عادةً هو الأكثر أهمية. تخزِّن
location_type
بيانات إضافية عن الموقع الجغرافي المحدّد. في ما يلي القيم المسموح بها حاليًا:- يشير الرمز
"ROOFTOP"
إلى أنّ النتيجة المعروضة هي رمز جغرافي دقيق تتوفّر لدينا معلومات الموقع الجغرافي له بدقة تصل إلى عنوان الشارع. - يشير الرمز
"RANGE_INTERPOLATED"
إلى أنّ النتيجة المعروضة تعكس قيمة تقريبية (عادةً على طريق) تمّت إضافتها بين نقطتَين دقيقتَين (مثل التقاطعات). يتم بشكل عام عرض النتائج التي تمّت الاستقراء فيها عندما لا تتوفّر رموز جغرافية لسطح المنزل لعنوان شارع معيّن. - يشير الرمز
"GEOMETRIC_CENTER"
إلى أنّه النتيجة المعروضة هي المركز الهندسي ل نتيجة مثل شكل متعدد الأضلاع (مثل شارع) أو مضلع (منطقة). - يشير الرمز
"APPROXIMATE"
إلى أنّ النتيجة المعروضة تقريبية.
- يشير الرمز
- يحتوي
viewport
على إطار العرض المقترَح لعرض النتيجة المعروضة، ويتم تحديده كقيمتَي خط عرض وخط طول تحدّدانsouthwest
وnortheast
زاوية مربّع حدود إطار العرض. بشكل عام، يتم استخدام مساحة العرض لعرض نتيجة عند عرضها للمستخدم. bounds
(يتم عرضها اختياريًا) لتخزين مربّع الحدود الذي يمكن أن يحتوي على النتيجة المعروضة بالكامل. يُرجى العِلم أنّ هذه الحدود قد لا تتطابق مع مساحة العرض المقترَحة. (على سبيل المثال، تتضمّن مدينة سان فرانسيسكو جزر فارالون التي تشكّل جزءًا من المدينة من الناحية الفنية، ولكن من المحتمل ألا يتم عرضها في إطار العرض).
- يحتوي الحقل
-
plus_code
(راجِع رمز الموقع المفتوح ورموز Plus Codes) هو مرجع موقع جغرافي مشفَّر، يتم الحصول عليه من إحداثيات خطوط الطول والعرض، ويمثّل منطقة: 1/8000 من الدرجة في 1/8000 من الدرجة (حوالي 14 مترًا في 14 مترًا عند خط الاستواء) أو أصغر. يمكن استخدام رموز Plus Codes كبديل لعناوين الشوارع في الأماكن التي لا تتوفّر فيها عناوين (حيث لا يتم ترقيم المباني أو تسمية الشوارع). لا تعرض واجهة برمجة التطبيقات رموز Plus Codes في بعض الأحيان.عندما تعرض الخدمة رمز Plus Code، يتم تنسيقه كرمز عالمي ورمز مركب:
global_code
هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9).compound_code
هو رمز محلي مكوّن من 6 أحرف أو أكثر يتضمّن موقعًا جغرافيًا واضحًا (CWC8+R9، ماونتن فيو، كاليفورنيا، الولايات المتحدة الأمريكية). لا تُحلِّل هذا المحتوى آليًا.
-
يشير الرمز
partial_match
إلى أنّ أداة ترميز المواقع الجغرافية لم تُعرِض مطابقة تامّة للطلب الأصلي، إلا أنّها تمكّنت من مطابقة جزء من العنوان المطلوب. ننصحك بمراجعة الطلب الأصلي بحثًا عن أخطاء إملائية و/أو عنوان غير كامل.تحدث المطابقات الجزئية في أغلب الأحيان لعناوين الشوارع التي لا تقع ضمن المنطقة المحلية التي تُدخلها في الطلب. وقد يتم أيضًا عرض مطابقات جزئية عندما يتطابق الطلب مع موقعين جغرافيين أو أكثر في المنطقة المحلية نفسها. على سبيل المثال، سيعرض العنوان "شارع هيلبار، بريستول، المملكة المتحدة" مطابقة جزئية لكل من شارع هنري وشارع هنريتا. يُرجى العِلم أنّه إذا كان الطلب يتضمّن عنصرًا في العنوان مكتوبًا بشكلٍ خاطئ، قد تقترح خدمة الترميز الجغرافي عنوانًا بديلاً. وسيتم أيضًا وضع علامة على الاقتراحات التي يتم عرضها بهذه الطريقة على أنّها مطابقة جزئية.
place_id
هو معرّف فريد يمكن استخدامه مع واجهات برمجة تطبيقات Google الأخرى. على سبيل المثال، يمكنك استخدامplace_id
في طلب Places API للحصول على تفاصيل نشاط تجاري محلي، مثل رقم الهاتف وساعات العمل ومراجعات مستخدمي التطبيق وغير ذلك. اطّلِع على نظرة عامة على رقم تعريف المكان.
أنواع العناوين وأنواع مكونات العناوين
تشير صفيف types[]
في النتيجة إلى
نوع العنوان. تشمل أمثلة أنواع العناوين عنوان شارع أو
بلدًا أو كيانًا سياسيًا. تتوفّر أيضًا مصفوفة types[]
في
address_components[]
، تشير إلى نوع كل جزء من
العنوان. وتشمل الأمثلة رقم الشارع أو البلد. (في ما يلي قائمة كاملة بأنواع
.) قد تحتوي العناوين على أنواع متعددة. يمكن اعتبار الأنواع "علامات".
على سبيل المثال، يتم وضع علامة على العديد من المدن باستخدام النوعَين political
و
locality
.
تتيح خدمة الترميز الجغرافي الأنواع التالية وتُرجعها في كلّ من صفيفَي نوع العنوان ونوع عنصر العنوان:
- يشير الرمز
street_address
إلى عنوان شارع دقيق. - يشير الرمز
route
إلى مسار يحمل اسمًا (مثل "US 101"). - يشير الرمز
intersection
إلى تقاطع رئيسي، عادةً ما يكون بين طريقين رئيسيتين. - يشير الرمز
political
إلى كيان سياسي. يشير هذا النوع عادةً إلى مضلّع لبعض الإدارات المدنية. - يشير الرمز
country
إلى الكيان السياسي الوطني، وهو عادةً نوع الترتيب الأعلى الذي يعرضه "محوِّل الرموز الجغرافية". - يشير الرمز
administrative_area_level_1
إلى كيان مدني من الدرجة الأولى يقع تحت مستوى البلد. في الولايات المتحدة، تُمثّل هذه المستويات الإدارية الولايات. لا تعتمد بعض البلدان هذه المستويات الإدارية. في معظم الحالات، تتوافق الأسماء المختصرة لسمة administrative_area_level_1 بشكل وثيق مع التقسيمات الفرعية لـ ISO 3166-2 والقوائم الأخرى المتداولة على نطاق واسع، ولكن لا يمكن ضمان ذلك لأنّ نتائج الترميز الجغرافي تستند إلى مجموعة متنوعة من الإشارات وبيانات الموقع الجغرافي. - يشير الرمز
administrative_area_level_2
إلى كيان مدني من الدرجة الثانية يتبع مستوى البلد. في الولايات المتحدة، تُعرف هذه المستويات الإدارية باسم المقاطعات. لا تعتمد بعض البلدان هذه المستويات الإدارية. - يشير الرمز
administrative_area_level_3
إلى كيان مدني من الدرجة الثالثة دون مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. لا تستخدم بعض البلدان هذه المستويات الإدارية. - يشير الرمز
administrative_area_level_4
إلى كيان مدني من الدرجة الرابعة يقع ضمن مستوى أقل من مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. لا تستخدم بعض البلدان هذه المستويات الإدارية. - يشير الرمز
administrative_area_level_5
إلى كيان مدني من الدرجة الخامسة دون مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. لا تستخدم بعض البلدان هذه المستويات الإدارية. - يشير الرمز
administrative_area_level_6
إلى كيان مدني من الدرجة السادسة دون مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. لا تستخدم بعض البلدان هذه المستويات الإدارية. - يشير الرمز
administrative_area_level_7
إلى كيان مدني من الدرجة السابعة يقع تحت مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. لا تستخدم بعض البلدان هذه المستويات الإدارية. - يشير الرمز
colloquial_area
إلى اسم بديل مستخدم بشكل شائع للكيان. - يشير الرمز
locality
إلى كيانٍ إداري مدمج لمدينة أو بلدة. - يشير الرمز
sublocality
إلى كيان مدني من الدرجة الأولى ضمن منطقة محلية. قد تتلقّى بعض المواقع الجغرافية أحد الأنواع الإضافية التالية:sublocality_level_1
إلىsublocality_level_5
. كل مستوى من مستويات الوحدات الفرعية للمناطق هو كيان مدني. تشير الأرقام الأكبر إلى منطقة جغرافية أصغر. - يشير الرمز
neighborhood
إلى حي يحمل اسمًا. - يشير الرمز
premise
إلى موقع جغرافي يحمل اسمًا، وعادةً ما يكون مبنى أو مجموعة من المباني تحمل اسمًا شائعًا. - يشير الرمز
subpremise
إلى عنصر قابل للعنوان أسفل مستوى الموقع، مثل شقة أو وحدة أو جناح. - يشير الرمز
plus_code
إلى مرجع موقع جغرافي مشفَّر تم اشتقاقه من خط العرض وخط الطول. يمكن استخدام رموز Plus Codes كبديل لعناوين الشوارع في الأماكن التي لا تتوفّر فيها (حيث لا يتم ترقيم المباني أو تسمية الشوارع). يُرجى الانتقال إلى https://plus.codes للاطّلاع على التفاصيل. - يشير الرمز
postal_code
إلى رمز بريدي كما هو مستخدَم في توجيه الرسائل البريدية داخل البلد. - يشير الرمز
natural_feature
إلى معلم طبيعي بارز. - يشير الرمز
airport
إلى مطار. - يشير الرمز
park
إلى متنزه يحمل اسمًا. - يشير الرمز
point_of_interest
إلى نقطة اهتمام مُسمّاة. وعادةً ما تكون "نقاط الاهتمام" هذه كيانات محلية بارزة لا يمكن بسهولة وضعها في فئة أخرى، مثل "مبنى إمباير ستيت" أو "برج إيفل".
تشير القائمة الفارغة للأنواع إلى عدم توفّر أنواع معروفة لمكوّن العنوان المعيّن، على سبيل المثال، Lieu-dit في فرنسا.
بالإضافة إلى ما سبق، قد تتضمّن مكونات العنوان الأنواع المدرَجة هنا. هذه القائمة ليست شاملة، وتخضع للتغيير.
- يشير الرمز
floor
إلى طابق عنوان المبنى. - يشير الرمز
establishment
عادةً إلى مكان لم يتم تصنيفه بعد. - يشير الرمز
landmark
إلى مكان قريب يُستخدَم كمرجع، لمساعدة المستخدمين في التنقّل. - يشير الرمز
point_of_interest
إلى نقطة اهتمام مُسمّاة. - يشير الرمز
parking
إلى موقف سيارات أو مبنى للسيارات. - يشير الرمز
post_box
إلى صندوق بريدي محدّد. - يشير الرمز
postal_town
إلى مجموعة من المناطق الجغرافية، مثلlocality
وsublocality
، المستخدَمة للعناوين البريدية في بعض البلدان. - يشير الرمز
room
إلى غرفة في عنوان مبنى. - يشير
street_number
إلى رقم الشارع الدقيق. - يشير الرمزان
bus_station
وtrain_station
وtransit_station
إلى موقع حافلة أو قطار أو محطة نقل عام.
تحيز إطار العرض
في طلب ترميز جغرافي، يمكنك توجيه خدمة الترميز الجغرافي إلى تفضيل
النتائج ضمن إطار عرض معيّن (يتم التعبير عنه كإطار حدودي). يمكنك إجراء ذلك
في عنوان URL للطلب من خلال ضبط المَعلمة bounds
.
تحدّد المَعلمة bounds
إحداثيات خط العرض/خط الطول
لركنَي الجنوب الغربي والشمال الشرقي من هذا المربّع الحدودي باستخدام حرف التوجيه
(|
) لفصل الإحداثيات.
على سبيل المثال، يعرض الرمز الجغرافي لـ "واشنطن" بشكل عام ولاية واشنطن في الولايات المتحدة:
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
الردّ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
ومع ذلك، يؤدي إضافة وسيطة bounds
تحدّد مربّعًا حدوديًا حول
الجزء الشمالي الشرقي من الولايات المتحدة إلى عرض هذا الرمز الجغرافي لمدينة
واشنطن العاصمة:
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
الردّ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
الانحياز إلى منطقة معيّنة
في طلب ترميز جغرافي، يمكنك توجيه خدمة الترميز الجغرافي لعرض results منحازة لمنطقة معيّنة باستخدام المَعلمة region
. تأخذ هذه المَعلمة مَعلمة ccTLD (نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد) لتحديد الانحياز إلى المنطقة. تتطابق معظم رموز نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد (ccTLD) مع رموقبميار ISO 3166-1، مع بعض الاستثناءات البارزة. على سبيل المثال، رمز النطاق العلوي العام لبريطانيا
المتحدة هو "uk" (.co.uk
) بينما رمزه وفقًا لمعيار ISO 3166-1 هو "gb"
(من الناحية الفنية، يشير إلى رمز "المملكة المتحدة لبريطانيا العظمى
وأيرلندا الشمالية").
يمكن أن تكون نتائج ترميز الموقع الجغرافي متحيّزة لكل نطاق يتم فيه إطلاق تطبيق "خرائط Google" الرئيسي رسميًا. يُرجى العلم أنّ منح الأولوية لن يؤدي إلا إلى منح الأولوية لنتائج نطاق معيّن. وإذا كانت هناك نتائج أكثر صلة خارج هذا النطاق، قد يتم تضمينها.
على سبيل المثال، يعرض رمز جغرافي لمدينة "تولّدو" هذه النتيجة، لأنّ النطاق التلقائي لواجهة برمجة التطبيقات Geocoding API تم ضبطه على الولايات المتحدة. الطلب:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
الردّ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
سيؤدي طلب ترميز جغرافي لـ "طليطلة" مع region=es
(إسبانيا) إلى
عرض المدينة الإسبانية.
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
الردّ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Toledo",
"short_name" : "TO",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
فلترة المكوّنات
في ردّ Geocoding API، يمكن أن تعرض واجهة برمجة التطبيقات Geocoding API نتائج عناوين محدودة على منطقة معيّنة. يمكنك تحديد القيود باستخدام
فلتر components
. يتألّف الفلتر من قائمة ب pairs
component:value
مفصولة بفاصلة (|
).
تتوافق قيم الفلتر مع طرق تصحيح الأخطاء الإملائية والمطابقة الجزئية نفسها المستخدَمة في طلبات ترميز المواقع الجغرافية الأخرى. إذا عثر برنامج ترميز المواقع الجغرافية على تطابق جزئي مع أحد فلاتر
المكوّنات، سيحتوي الردّ على حقل partial_match
.
تشمل components
التي يمكن فلترتها ما يلي:
- يتطابق
postal_code
معpostal_code
وpostal_code_prefix
. - تتطابق القيمة
country
مع اسم بلد أو رمز بلد مكوّن من حرفَين تبعًا لـ ISO 3166-1 تلتزم واجهة برمجة التطبيقات بمعيار ISO لتحديد البلدان، وتعمل الفلترة على أفضل نحو عند استخدام رمز ISO المقابل للبلد.
يمكن استخدام components
التالية للتأثير في النتائج، ولكن لن يتم
فرضها:
route
يتطابق مع الاسم الطويل أو القصير للمسار.- تتطابق
locality
مع النوعَينlocality
وsublocality
. - يتطابق
administrative_area
مع جميعadministrative_area
المستويات.
ملاحظات حول فلترة المكوّنات:
- لا تكرِّر فلاتر المكوّنات هذه في الطلبات، وإلا ستُعرِض واجهة برمجة التطبيقات القيمة التالية:
Invalid_request
:country
وpostal_code
route
- إذا كان الطلب يحتوي على فلاتر مكوّنات متكرّرة، تقيِّم واجهة برمجة التطبيقات تلك الفلاتر على أنّها عملية "و"، وليس "أو".
- تتطابق النتائج مع "خرائط Google"، التي تؤدي أحيانًا إلى
ظهور ردود
ZERO_RESULTS
غير متوقّعة. قد يؤدي استخدام ميزة "الإكمال التلقائي للأماكن" إلى تقديم نتائج أفضل في بعض حالات الاستخدام. لمزيد من المعلومات، يُرجى الاطّلاع على هذه الأسئلة الشائعة. - لكل مكوّن من مكوّنات العنوان، حدِّده في المَعلمة
address
أو في فلترcomponents
، ولكن ليس كليهما. قد يؤدي تحديد القيم نفسها في كلتا السمتَين إلى ظهورZERO_RESULTS
.
يعرض الرمز الجغرافي لـ "High St, Hastings" مع components=country:GB
نتيجة في هاستينغز، إنجلترا بدلاً من هاستينغز-إن-هدسون، الولايات المتحدة الأمريكية.
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
الردّ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
طلب رمز جغرافي للمنطقة المحلية "سانتا كروز" باستخدام components=country:ES
يعرض سانتا كروز دي تينيريفي في جزر الكناري، إسبانيا.
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
الردّ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "Santa Cruz de Tenerife",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Santa Cruz de Tenerife, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
},
"location" : {
"lat" : 28.4636296,
"lng" : -16.2518467
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
}
},
"place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
لا تعرِض فلترة المكوّنات استجابة ZERO_RESULTS
إلا إذا قدّمت فلاتر تستبعد بعضها.
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
الردّ:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
يمكنك إجراء طلبات بحث صالحة بدون مَعلمة العنوان باستخدام فلتر
components
. (عند ترميز عنوان كامل جغرافيًا، يجب استخدام المَعلمة address
إذا كان الطلب يحتوي على أسماء المباني وأرقامها).
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
الردّ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}