الطلب
يظهر طلب Geocoding API على النحو التالي:
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
يجب تنسيق رموز Plus Codes كما هو موضّح هنا (يتم استبعاد علامات الجمع من خلال تجاوز عنوان 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
— هو رمز المنطقة الذي يتم تحديده على أنّه قيمة مؤلفة من حرفَين لنطاق المستوى الأعلى التي يتم ترميزها حسب البلد ("نطاق المستوى الأعلى") . ستؤثّر هذه المَعلمة فقط في النتائج الواردة من أداة الترميز الجغرافي، ولن تؤثر فيها بشكل كامل. (لمزيد من المعلومات، راجِع انحياز المنطقة أدناه.) ويمكن أن تؤثر المَعلمة أيضًا في النتائج استنادًا إلى القانون الساري.components
— فلتر للمكوّنات يحتوي على عناصر مفصولة بشرطة (|
)، ويكون فلتر المكونات مطلوبًا إذا لم يتضمن الطلبaddress
. يتألف كل عنصر في فلتر المكوّنات من زوجcomponent:value
، ويقيّد النتائج من أداة الترميز الجغرافي بشكل كامل. يمكنك الاطّلاع أدناه على مزيد من المعلومات حول فلترة المكوّنات.extra_computations
— القيمة الوحيدة المسموح بها لهذه المعلَمة هيADDRESS_DESCRIPTORS
. راجِع أدوات وصف العناوين للحصول على مزيد من التفاصيل.
الردود
يتم عرض استجابات الترميز الجغرافي بالتنسيق المُشار إليه في علامة 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"
لعمليات البحث عن العناوين، على الرغم من أنّ برنامج الترميز الجغرافي قد يعرض عدة نتائج عندما تكون طلبات البحث عن العناوين غامضة.
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"
في كائن الاستجابة Geocoding حالة الطلب، وقد يحتوي على معلومات تصحيح الأخطاء لمساعدتك في تعقب سبب عدم عمل الترميز الجغرافي. قد يحتوي الحقل "status"
على القيم التالية:
- تشير القيمة
"OK"
إلى عدم حدوث أي أخطاء، وأنّه تم تحليل العنوان بنجاح وتم عرض رمز جغرافي واحد على الأقل. - تشير القيمة
"ZERO_RESULTS"
إلى أن الترميز الجغرافي كان ناجحًا ولكنه لم يعرض أي نتائج. قد يحدث ذلك إذا تم تمرير أداة الترميز الجغرافي إلى علامةaddress
غير موجودة. - تشير السمة
OVER_DAILY_LIMIT
إلى أي مما يلي:- مفتاح واجهة برمجة التطبيقات مفقود أو غير صالح.
- لم يتم تفعيل الفوترة في حسابك.
- تم تجاوز الحد الأقصى المسموح به للاستخدام.
- لم تعُد طريقة الدفع المقدّمة صالحة (على سبيل المثال، انتهت صلاحية بطاقة ائتمان).
اطّلِع على الأسئلة الشائعة حول "خرائط Google" لمعرفة كيفية حلّ هذه المشكلة.
- تشير القيمة
"OVER_QUERY_LIMIT"
إلى أنك تجاوزت حصتك. - تشير القيمة
"REQUEST_DENIED"
إلى أنّه تم رفض طلبك. - بشكل عام، تشير السمة
"INVALID_REQUEST"
إلى أنّ طلب البحث (address
أوcomponents
أوlatlng
) غير متوفّر. - وتشير القيمة
"UNKNOWN_ERROR"
إلى تعذُّر معالجة الطلب بسبب خطأ في الخادم. قد يتم تنفيذ الطلب في حال إعادة المحاولة.
رسائل الخطأ
عندما يعرض أداة الترميز الجغرافي رمز حالة غير OK
، قد يكون هناك حقل error_message
إضافي ضمن كائن الاستجابة الخاص بالترميز الجغرافي. يحتوي هذا الحقل على معلومات أكثر تفصيلاً حول
الأسباب الكامنة وراء رمز الحالة المعين.
النتائج
عندما يعرض برنامج الترميز الجغرافي النتائج، يضعها في مصفوفة results
(JSON). حتى إذا لم يعرض برنامج الترميز الجغرافي أي نتائج (مثلاً إذا كان العنوان غير متوفّر)، سيعرض مصفوفة results
فارغة. (تتألف استجابات XML من صفر أو أكثر من
عناصر <result>
.)
تحتوي النتيجة النموذجية على الحقول التالية:
- تشير مصفوفة
types[]
إلى type للنتيجة المعروضة. تحتوي هذه الصفيفة على مجموعة من العلامات صفر أو أكثر تحدد نوع الميزة المعروضة في النتيجة. على سبيل المثال، يعرض الرمز الجغرافي لـ "شيكاغو" كلمة "محلية" التي تشير إلى أن "شيكاغو" هي مدينة، ويعرض أيضًا كلمة "سياسية" التي تشير إلى أنها كيان سياسي. قد يكون للمكونات مصفوفة أنواع فارغة عندما لا تكون هناك أنواع معروفة لمكون العنوان هذا. قد تضيف واجهة برمجة التطبيقات قيم أنواع جديدة حسب الحاجة. لمزيد من المعلومات، يمكنك الاطّلاع على أنواع العناوين ومكوّناتها. - تمثّل
formatted_address
سلسلة تحتوي على عنوان يمكن لشخص عادي قراءته لهذا الموقع الجغرافي.وغالبًا ما يكون هذا العنوان مكافئًا للعنوان البريدي. يُرجى العلم أنّ بعض البلدان، مثل المملكة المتحدة، لا تسمح بتوزيع عناوين بريدية حقيقية بسبب القيود المفروضة على الترخيص.
يتكون العنوان بالتنسيق منطقيًا من واحد أو أكثر من مكوّنات العنوان. على سبيل المثال، يتكوّن العنوان "111 8th Avenue, New York, NY" من العناصر التالية: "111" (رقم الشارع) و"8th Avenue" (الطريق) و"نيويورك" (المدينة) و "NY" (الولاية الأمريكية).
عدم تحليل العنوان المنسَّق آليًا. وبدلاً من ذلك، عليك استخدام مكوّنات العنوان الفردي، والتي يتضمّنها ردّ واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.
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
(يُرجى الاطّلاع على رمز الموقع الجغرافي المفتوح ورموز المواقع الجغرافية) هو مرجع مشفّر للموقع الجغرافي، وهو مشتق من إحداثيات خطوط الطول والعرض، ويمثّل المنطقة: 1/8, 000 درجة x 1/8, 000 درجة (حوالي 14 متر x 14 متر عند خط الاستواء) أو أصغر. يمكن استخدام رموز Plus Codes كبديل لعناوين الشوارع في الأماكن التي لا توجد فيها العناوين (حيث لا تكون المباني مرقمة أو لا تحمل أسماء الشوارع). لا تعرض واجهة برمجة التطبيقات دائمًا رموز المواقع المفتوحة.عندما تعرض الخدمة رمز Plus Codes، يتم تنسيقه كرمز عمومي ورمز مركّب:
global_code
هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوَّن من 6 أحرف أو أكثر (849VCWC8+R9).compound_code
هو رمز محلي مكوَّن من 6 أحرف أو أكثر ويتميّز بموقع جغرافي فاضح (CWC8+R9، ماونتن فيو، كاليفورنيا، الولايات المتحدة). ويُرجى عدم تحليل هذا المحتوى آليًا.
-
تشير
partial_match
إلى أن برنامج الترميز الجغرافي لم يعرض تطابقًا تامًا للطلب الأصلي، على الرغم من أنه كان قادرًا على مطابقة جزء من العنوان المطلوب. يمكنك مراجعة الطلب الأصلي بحثًا عن أخطاء إملائية و/أو العنوان غير المكتمل.فغالبًا ما تحدث مطابقات جزئية لعناوين الشوارع التي لا توجد داخل المنطقة المحلية التي تم تمريرها في الطلب. وقد يتم عرض المطابقات الجزئية أيضًا عندما يتطابق طلب مع موقعين جغرافيين أو أكثر في المنطقة المحلية نفسها. على سبيل المثال، سيعرض "شارع السلام، القاهرة، الإمارات العربية المتحدة" نتيجة مطابقة جزئية لكل من شارعين حسين وشارع مصطفى المهندسين. يُرجى ملاحظة أنّه إذا تضمّن الطلب مكوّن عنوان به خطأ إملائي، قد تقترح خدمة الترميز الجغرافي عنوانًا بديلاً. سيتم أيضًا وضع علامة على الاقتراحات التي يتم تشغيلها بهذه الطريقة على أنّها مطابقة جزئية.
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"
}
فلترة المكوّنات
في استجابة Geocoding API، يمكن لواجهة Geocoding API عرض
نتائج عناوين مقصورة على منطقة معينة. يمكنك تحديد القيود باستخدام
فلتر components
. يتكون الفلتر من قائمة من
component:value
أزواج مفصولة بممر (|
).
تتيح قيم الفلاتر استخدام طرق التصحيح الإملائي والمطابقة الجزئية نفسها مثل طلبات الترميز الجغرافي الأخرى. إذا عثر أداة الترميز الجغرافي على تطابق جزئي لفلتر مكوّنات، ستحتوي الاستجابة على حقل partial_match
.
تتضمّن components
التي يمكن فلترتها ما يلي:
- تتطابق السمة
postal_code
معpostal_code
وpostal_code_prefix
. - تتطابق السمة
country
مع اسم البلد أو رمز البلد المكوّن من حرفَين ISO 3166-1. تتّبع واجهة برمجة التطبيقات معيار ISO لتحديد البلدان، وتعمل الفلاتر بشكل أفضل عند استخدام رمز ISO المناسب للبلد.
قد يتم استخدام سمة components
التالية للتأثير في النتائج، ولكن لن يتم فرضها:
- يتطابق
route
مع الاسم الطويل أو القصير لمسار. - يتطابق
locality
مع النوعينlocality
وsublocality
. - تتطابق السمة
administrative_area
مع جميع مستوياتadministrative_area
.
ملاحظات حول تصفية المكونات:
- لا تكرِّر هذه الفلاتر المكوِّنة في الطلبات، وإلا ستعرض واجهة برمجة التطبيقات
Invalid_request
:country
أوpostal_code
أوroute
- إذا كان الطلب يتضمّن فلاتر مكوّنات متكرّرة، تقيّم واجهة برمجة التطبيقات هذه الفلاتر باعتبارها عاملَي AND وليس OR.
- تتوافق النتائج مع "خرائط Google"، ما ينتج عنه في بعض الأحيان ردود غير متوقعة من
ZERO_RESULTS
. قد يؤدي استخدام ميزة "الإكمال التلقائي" للأماكن إلى تقديم نتائج أفضل في بعض حالات الاستخدام. لمزيد من المعلومات، يمكنك الاطّلاع على الأسئلة الشائعة هذه. - لكل مكوّن عنوان، يمكنك تحديده في المعلَمة
address
أو في فلترcomponents
، ولكن ليس في كليهما. وقد يؤدي تحديد القيم نفسها في كلتا الخدمتين إلى عرضZERO_RESULTS
.
الرمز الجغرافي لـ "High St, Hadson" مع 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"
}