الطلب
ويكون طلب واجهة برمجة التطبيقات للترميز الجغرافي بالشكل التالي:
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 Mountain View, CA, USA هو
CWC8%2BR9%20Mountain%20View%20CA%20USA).
--OR--
components— فلتر مكوّن يحتوي على عناصر مفصولة بشرطة (|). يتم أيضًا قبول فلتر المكوّنات كمعلَمة اختيارية في حال توفيرaddress. يتألّف كل عنصر في فلتر المكوّنات من زوج مكوّن منcomponent:value، كما يعمل على تقييد النتائج تمامًا من أداة الترميز الجغرافي. اطّلِع على مزيد من المعلومات حول فلترة المكوّنات أدناه.- الرمز العالمي هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9 هو
key— مفتاح واجهة برمجة التطبيقات للتطبيق. يحدّد هذا المفتاح تطبيقك لأغراض إدارة الحصص. تعرَّف على كيفية الحصول على مفتاح.
يُرجى الرجوع إلى الأسئلة الشائعة للحصول على إرشادات إضافية.
المعلّمات الاختيارية في طلب الترميز الجغرافي:
bounds— مربع الإحاطة لإطار العرض الذي يتم من خلاله انحياز النتائج جغرافيًا بشكل أكثر بروزًا. وستؤثر هذه المعلَمة فقط في النتائج الواردة من أداة الترميز الجغرافي، وليس حصرها بشكل كامل. (لمزيد من المعلومات، راجع انحياز إطار العرض أدناه.)language— اللغة التي سيتم عرض النتائج بها.- راجِع قائمة اللغات المتوافقة. غالبًا ما تحدّث Google اللغات المتوافقة، لذا قد لا تكون هذه القائمة شاملة.
- إذا لم يتم تقديم
language، يحاول برنامج الترميز الجغرافي استخدام اللغة المفضّلة على النحو المحدّد في العنوانAccept-Languageأو اللغة الأصلية للنطاق الذي يتم إرسال الطلب منه. - وتبذل أداة الترميز الجغرافي أقصى جهدها لتوفير عنوان شارع يمكن لكل من المستخدم والسكان المحليين قراءته. ولتحقيق هذا الهدف، تعرض علامة التبويب هذه عناوين الشوارع باللغة المحلية، ويتم تحويلها إلى نص برمجي يمكن للمستخدم قراءته، إذا لزم الأمر، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. ويتم عرض جميع مكوّنات العناوين باللغة نفسها التي يتم اختيارها من المكوِّن الأول.
- إذا لم يكن الاسم متوفّرًا باللغة المفضّلة، يستخدم برنامج الترميز الجغرافي التطابق الأقرب.
- وتؤثر اللغة المفضّلة تأثيرًا طفيفًا في مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها والترتيب الذي ستظهر به. يفسر برنامج الترميز الجغرافي الاختصارات بطريقة مختلفة استنادًا إلى اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في إحدى اللغات ولكنها لا تكون صالحة في لغة أخرى. على سبيل المثال، utca وtér مترادفان للشارع والمربّع على التوالي في المجرية.
region— رمز المنطقة المحدد بقيمة ccTLD ("نطاق المستوى الأعلى") من حرفين. وستؤثر هذه المعلَمة فقط في النتائج الواردة من أداة الترميز الجغرافي، وليس حصرها بشكل كامل. (لمزيد من المعلومات، راجع انحياز المنطقة أدناه.) ويمكن أن تؤثر المعلّمة أيضًا في النتائج استنادًا إلى القانون الساري.components— فلتر مكوّن يحتوي على عناصر مفصول بينها بشرطة (|). يكون فلتر المكونات مطلوبًا إذا لم يتضمن الطلبaddress. يتألّف كل عنصر في فلتر المكوّنات من زوج مكوّن منcomponent:value، كما يعمل على تقييد النتائج تمامًا من أداة الترميز الجغرافي. اطّلِع على مزيد من المعلومات حول فلترة المكوّنات أدناه.
الردود
يتم عرض استجابات الترميز الجغرافي بالتنسيق المُشار إليه في العلامة output ضمن طلب عنوان URL، أو بتنسيق JSON تلقائيًا.
في هذا المثال، تطلب واجهة برمجة التطبيقات للترميز الجغرافي استجابة json لطلب بحث عن رقم تعريف المكان "ChIJeRpOeF67j4AR9ydy_PIzPuM". هذا المكان
معرّف للمبنى في 1600 Amphitheatre Parkway, Mountain View, CA.
يوضح هذا الطلب باستخدام علامة JSON output:
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
يوضح هذا الطلب باستخدام علامة XML output:
https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
حدد علامات التبويب أدناه لمشاهدة نماذج استجابات JSON وXML.
JSON
{
"results": [
{
"address_components": [
{
"long_name": "1600",
"short_name": "1600",
"types": [
"street_number"
]
},
{
"long_name": "Amphitheatre Parkway",
"short_name": "Amphitheatre Pkwy",
"types": [
"route"
]
},
{
"long_name": "Mountain View",
"short_name": "Mountain View",
"types": [
"locality",
"political"
]
},
{
"long_name": "Santa Clara County",
"short_name": "Santa Clara County",
"types": [
"administrative_area_level_2",
"political"
]
},
{
"long_name": "California",
"short_name": "CA",
"types": [
"administrative_area_level_1",
"political"
]
},
{
"long_name": "United States",
"short_name": "US",
"types": [
"country",
"political"
]
},
{
"long_name": "94043",
"short_name": "94043",
"types": [
"postal_code"
]
}
],
"formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
"geometry": {
"location": {
"lat": 37.4224428,
"lng": -122.0842467
},
"location_type": "ROOFTOP",
"viewport": {
"northeast": {
"lat": 37.4239627802915,
"lng": -122.0829089197085
},
"southwest": {
"lat": 37.4212648197085,
"lng": -122.0856068802915
}
}
},
"place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
"plus_code": {
"compound_code": "CWC8+X8 Mountain View, CA",
"global_code": "849VCWC8+X8"
},
"types": [
"street_address"
]
}
],
"status": "OK"
}
لاحظ أن استجابة JSON تحتوي على عنصرين أساسيين:
- يحتوي
"status"على بيانات وصفية على الطلب. راجع رموز الحالة أدناه. - يحتوي
"results"على مجموعة من معلومات العنوان الهندسي بالإضافة إلى معلومات هندسية.
بشكل عام، يتم عرض إدخال واحد فقط في المصفوفة "results" لعمليات البحث عن العنوان، على الرغم من أن أداة الترميز الجغرافي قد تعرض عدة نتائج عندما تكون طلبات البحث عن العنوان غامضة.
XML
<GeocodeResponse>
<status>OK</status>
<result>
<type>street_address</type>
<formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
<address_component>
<long_name>1600</long_name>
<short_name>1600</short_name>
<type>street_number</type>
</address_component>
<address_component>
<long_name>Amphitheatre Parkway</long_name>
<short_name>Amphitheatre Pkwy</short_name>
<type>route</type>
</address_component>
<address_component>
<long_name>Mountain View</long_name>
<short_name>Mountain View</short_name>
<type>locality</type>
<type>political</type>
</address_component>
<address_component>
<long_name>Santa Clara County</long_name>
<short_name>Santa Clara County</short_name>
<type>administrative_area_level_2</type>
<type>political</type>
</address_component>
<address_component>
<long_name>California</long_name>
<short_name>CA</short_name>
<type>administrative_area_level_1</type>
<type>political</type>
</address_component>
<address_component>
<long_name>United States</long_name>
<short_name>US</short_name>
<type>country</type>
<type>political</type>
</address_component>
<address_component>
<long_name>94043</long_name>
<short_name>94043</short_name>
<type>postal_code</type>
</address_component>
<geometry>
<location>
<lat>37.4224428</lat>
<lng>-122.0842467</lng>
</location>
<location_type>ROOFTOP</location_type>
<viewport>
<southwest>
<lat>37.4212648</lat>
<lng>-122.0856069</lng>
</southwest>
<northeast>
<lat>37.4239628</lat>
<lng>-122.0829089</lng>
</northeast>
</viewport>
</geometry>
<place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id>
<plus_code>
<global_code>849VCWC8+X8</global_code>
<compound_code>CWC8+X8 Mountain View, CA</compound_code>
</plus_code>
</result>
</GeocodeResponse>
يُرجى العِلم بأنّ استجابة XML تتألّف من عنصر واحد
<GeocodeResponse> وعنصرَين من المستوى الأعلى:
- يحتوي
<status>على بيانات وصفية على الطلب. راجع رموز الحالة أدناه. - بدون عناصر
<result>أو أكثر، يحتوي كل عنصر على مجموعة واحدة من معلومات العنوان الجغرافي بالإضافة إلى المعلومات الهندسية.
وتكون استجابة XML أطول بكثير من استجابة JSON. ولهذا السبب، ننصحك باستخدام json كعلامة الإخراج المفضّلة ما لم تطلب الخدمة استخدام xml لسبب ما.
إضافةً إلى ذلك، تتطلّب معالجة أشجار XML بعض العناية كي تتمكن من الرجوع إلى العُقد والعناصر المناسبة. راجِع
تحليل XML باستخدام XPath للتعرُّف على بعض أنماط التصميم المقترَحة لمعالجة المُخرجات.
- يتم التفاف نتائج XML في عنصر
<GeocodeResponse>الجذر. - تشير JSON إلى الإدخالات التي تحتوي على عناصر متعددة من خلال مصفوفات الجمع (
types)، بينما تشير XML إلى هذه العناصر باستخدام عناصر المفرد المتعددة (<type>). - تتم الإشارة إلى العناصر الفارغة من خلال مصفوفات فارغة في JSON، ولكن بسبب عدم وجود أي عنصر من هذا القبيل في XML. ستعرض الاستجابة التي لا تؤدي إلى أي نتائج مصفوفة
resultsفارغة في JSON، ولكن لن تعرض أي عناصر<result>في XML على سبيل المثال.
رموز الحالة
يحتوي الحقل "status" في كائن الاستجابة "الترميز الجغرافي" على حالة الطلب، وقد يحتوي على معلومات تصحيح الأخطاء لمساعدتك في تتبع سبب عدم عمل الترميز الجغرافي. قد يحتوي الحقل "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 8th Avenue, New York, NY" من المكوّنات التالية: "111" (رقم الشارع) و"8th Avenue" (المسار) و"New York" (المدينة) و "NY" (ولاية الولايات المتحدة).
عدم تحليل العنوان المنسَّق آليًا. وبدلاً من ذلك، عليك استخدام مكوّنات العناوين الفردية، التي تتضمّن استجابة واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.
address_components[]عبارة عن مصفوفة تحتوي على المكونات المنفصلة السارية على هذا العنوان.يحتوي كل مكون من مكونات العنوان عادةً على الحقول التالية:
types[]عبارة عن مصفوفة تشير إلى نوع مكوِّن العنوان. اطّلِع على قائمة الأنواع المتوافقة.long_nameهو الوصف النصي الكامل أو اسم مكوّن العنوان كما هو مكتوب بواسطة Geocoder.short_nameهو اسم نصي مختصر لمكوّن العنوان، إن وجد. على سبيل المثال، قد يحتوي مكوّن العنوان لولاية ألاسكا علىlong_nameمن "ألاسكا" وshort_nameمن "AK" باستخدام الاختصار البريدي المكوّن من حرفين.
يُرجى ملاحظة الحقائق التالية حول مصفوفة
address_components[]:- قد تحتوي مصفوفة مكونات العنوان على مكونات أكثر من
formatted_address. - لا تشمل المصفوفة بالضرورة جميع الكيانات السياسية التي تحتوي على عنوان، باستثناء الكيانات المُدرَجة في
formatted_address. لاسترداد جميع الكيانات السياسية التي تحتوي على عنوان معين، يجب استخدام الترميز الجغرافي العكسي، وتمرير خط العرض/الطول للعنوان كمعلمة للطلب. - لا يمكن ضمان بقاء تنسيق الاستجابة كما هو بين الطلبات. على وجه الخصوص، يختلف عدد
address_componentsبناءً على العنوان المطلوب ويمكن أن يتغيّر بمرور الوقت للعنوان نفسه. يمكن لأحد المكونات تغيير الموضع في المصفوفة. يمكن تغيير نوع المكوِّن. قد يكون أحد المكوّنات غير متوفّر في استجابة لاحقة.
لمعالجة مصفوفة المكوّنات، يجب تحليل الاستجابة واختيار القيم المناسبة من خلال التعبيرات. يمكنك الاطلاع على دليل تحليل استجابة.
postcode_localities[]هي مصفوفة تشير إلى جميع المناطق المحلية المضمّنة في رمز بريدي. لا يتوفّر هذا الخيار إلا إذا كانت النتيجة عبارة عن رمز بريدي يتضمّن عدّة مناطق محلية.- يحتوي
geometryعلى المعلومات التالية:- يحتوي
locationعلى قيمة خط الطول وخط العرض جغرافيًا. وبالنسبة إلى عمليات البحث العادية عن العنوان، عادةً ما يكون هذا الحقل هو الأكثر أهمية. يخزن
location_typeبيانات إضافية حول الموقع المحدد. القيم التالية متاحة حاليًا:- تشير القيمة
"ROOFTOP"إلى أن النتيجة المعروضة هي رمز جغرافي دقيق تم تعيين معلومات الموقع الجغرافي الخاصة به إلى دقة عنوان الشارع. - تشير القيمة
"RANGE_INTERPOLATED"إلى أن النتيجة المعروضة تعكس تقريبيًا (عادةً على طريق) بين نقطتين دقيقتين (مثل التقاطعات). ويتم عادةً عرض النتائج المضافة عندما تكون الرموز الجغرافية على سطح المكتب غير متاحة لعنوان الشارع. - تشير القيمة
"GEOMETRIC_CENTER"إلى أن النتيجة المعروضة هي المركز الهندسي لنتيجة مثل الخطوط المتعددة (مثل الشوارع) أو المضلّع (المنطقة). - تشير علامة
"APPROXIMATE"إلى أن النتيجة المعروضة تقريبية.
- تشير القيمة
- يتضمّن
viewportإطار العرض المقترَح لعرض النتيجة المعروضة، وهي قيمتَين لخط الطول وخط العرض تحدّدان ركنَيsouthwestوnortheastلمربّع إحاطة إطار العرض. ويتم عادةً استخدام إطار العرض لتأطير نتيجة عند عرضها لمستخدم. bounds(يتم إرجاعها بشكل اختياري) إلى تخزين مربع الإحاطة الذي يمكن أن يحتوي على النتيجة المعروضة بالكامل. يُرجى العِلم بأنّ هذه الحدود قد لا تتطابق مع إطار العرض المقترَح. (على سبيل المثال، تشمل مدينة سان فرانسيسكو جزر الفرالون، التي تُعد جزءًا من المدينة من الناحية الفنية، ولكن من المحتمل عدم عرضها في إطار العرض).
- يحتوي
-
plus_code(راجع رمز الموقع المفتوح ورموز المواقع المفتوحة) عبارة عن مرجع موقع مشفر، مستمد من إحداثيات خطوط العرض وخطوط الطول، ويمثل المنطقة: 1/8000 من الدرجة بمقدار 1/8000 من الدرجة (حوالي 14 متر × 14 مترًا في خط الاستواء) أو أصغر. يمكن استخدام رموز المواقع المفتوحة كبديل لعناوين الشوارع في الأماكن التي لا توجد بها عناوين (حيث لا تكون المباني مرقمة أو لا تتم تسمية الشوارع فيها). لا تعرض واجهة برمجة التطبيقات دائمًا رموز المواقع المفتوحة.عندما تعرض الخدمة رمز الموقع المفتوح، يتم تنسيقه كرمز عام ورمز مركّب:
global_codeهو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9).compound_codeهو رمز محلي مكون من 6 أحرف أو أكثر يتضمّن موقعًا جغرافيًا صريحًا (CWC8+R9, Mountain View, CA, USA). لا تحلل هذا المحتوى برمجيًا.
-
تشير القيمة
partial_matchإلى أن أداة الترميز الجغرافي لم تعرض مطابقة تامة للطلب الأصلي، على الرغم من أنها تمكنت من مطابقة جزء من العنوان المطلوب. وقد تحتاج إلى فحص الطلب الأصلي بحثًا عن أخطاء إملائية و/أو عنوان غير مكتمل.غالبًا ما تحدث المطابقات الجزئية لعناوين الشوارع غير الموجودة في المنطقة المحلية التي تمرر فيها الطلب. ويمكن أيضًا عرض المطابقات الجزئية عندما يتطابق الطلب مع موقعَين أو أكثر في المنطقة المحلية نفسها. على سبيل المثال، سينتج عن عبارة "Hillpar St, Bristol, UK" تطابق جزئي لكل من شارع هنري وشارع هنريتا. لاحظ أنه إذا كان الطلب يشتمل على مكون عنوان خطأ إملائي، فقد تقترح خدمة الترميز الجغرافي عنوانًا بديلاً. سيتم أيضًا وضع علامة على الاقتراحات التي يتم تشغيلها بهذه الطريقة كمطابقة جزئية.
place_idهو معرّف فريد يمكن استخدامه مع واجهات برمجة تطبيقات أخرى من Google. على سبيل المثال، يمكنك استخدامplace_idفي طلب واجهة برمجة تطبيقات الأماكن للحصول على تفاصيل نشاط تجاري محلي، مثل رقم الهاتف وساعات العمل ومراجعات المستخدمين والمزيد. اطّلِع على نظرة عامة على رقم تعريف المكان.
أنواع العناوين وأنواع مكونات العنوان
تشير صفيف types[] في النتيجة إلى
نوع العنوان. تشمل أمثلة أنواع العناوين عنوان الشارع أو البلد أو الكيان السياسي. هناك أيضًا مصفوفة types[] في
address_components[]، تشير إلى نوع كل جزء من
العنوان. تشمل الأمثلة رقم الشارع أو البلد. (في ما يلي قائمة كاملة بالأنواع.) قد تكون العناوين متعددة الأنواع. يمكن اعتبار الأنواع "علامات".
على سبيل المثال، يتم وضع علامات على العديد من المدن باستخدام النوع political والسمة locality.
يتم دعم الأنواع التالية وعرضها بواسطة أداة الترميز الجغرافي في كل من مصفوفات نوع العنوان ونوع مكوّن العنوان:
- يشير
street_addressإلى عنوان شارع دقيق. - تشير القيمة
routeإلى مسار مسمّى (مثل "US 101"). - تشير علامة
intersectionإلى تقاطع رئيسي، يتألف عادةً من طريقين رئيسيين. - تشير القيمة
politicalإلى كيان سياسي. يشير هذا النوع عادةً إلى مضلع بعض الإدارة المدنية. - يشير
countryإلى الكيان السياسي الوطني، وهو عادةً أعلى نوع من الطلبات يعرضه برنامج الترميز الجغرافي. - تشير السمة
administrative_area_level_1إلى كيان مدني من الدرجة الأولى أسفل مستوى البلد. في الولايات المتحدة، تكون هذه المستويات الإدارية ولايات. ولا تعرض جميع الدول هذه المستويات الإدارية. في معظم الحالات، تتطابق الأسماء المختصرة على مستوى ISO_area_level_1 بشكل وثيق مع الأقسام الفرعية ISO 3166-2 والقوائم الأخرى المتداولة على نطاق واسع، إلا أن هذا لا يمكن ضمانه لأن نتائج الترميز الجغرافي تستند إلى إشارات متنوعة وبيانات موقع جغرافي. - تشير الخاصية
administrative_area_level_2إلى كيان مدني من الدرجة الثانية أسفل مستوى البلد. وتندرج هذه المستويات الإدارية في الولايات المتحدة ضمن المقاطعات. ولا تعرض جميع الدول هذه المستويات الإدارية. - تشير السمة
administrative_area_level_3إلى كيان مدني من الدرجة الثالثة أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. ولا تعرض جميع الدول هذه المستويات الإدارية. - تشير السمة
administrative_area_level_4إلى كيان مدني من المستوى الرابع أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. ولا تعرض جميع الدول هذه المستويات الإدارية. - تشير القيمة
administrative_area_level_5إلى كيان مدني ذي ترتيب خامس أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. ولا تعرض جميع الدول هذه المستويات الإدارية. - تشير القيمة
administrative_area_level_6إلى كيان مدني من المستوى السادس أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. ولا تعرض جميع الدول هذه المستويات الإدارية. - تشير القيمة
administrative_area_level_7إلى كيان مدني من المستوى السابع أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. ولا تعرض جميع الدول هذه المستويات الإدارية. - تشير السمة
colloquial_areaإلى اسم بديل شائع الاستخدام للكيان. - تشير القيمة
localityإلى كيان سياسي مضمّن في مدينة أو بلدة. - تشير الخاصية
sublocalityإلى الكيان المدني من الدرجة الأولى أسفل المنطقة المحلية. بالنسبة إلى بعض المواقع الجغرافية، قد تتلقّى أحد الأنواع الإضافية:sublocality_level_1إلىsublocality_level_5. كل مستوى من مستويات المنطقة المحلية الفرعية هو كيان مدني. وتشير الأرقام الأكبر إلى مساحة جغرافية أصغر. - يشير
neighborhoodإلى حي مُعنون - تشير علامة
premiseإلى موقع جغرافي مُسمّى، وعادةً ما يكون مبنى أو مجموعة من المباني ذات الاسم الشائع. - تشير علامة
subpremiseإلى كيان من المستوى الأول أسفل موقع جغرافي محدّد، ويكون عادةً مبنى واحدًا ضمن مجموعة من المباني ذات الاسم الشائع. - يشير
plus_codeإلى مرجع موقع مشفر، مستمد من خط العرض وخط الطول. يمكن استخدام رموز المواقع المفتوحة كبديل لعناوين الشوارع في الأماكن التي لا توجد فيها (حيث لا تكون المباني مرقمة أو لا تحمل أسماء الشوارع). راجع https://plus.codes للحصول على التفاصيل. - تشير السمة
postal_codeإلى رمز بريدي يُستخدم للتعامل مع البريد البريدي داخل البلد. - تشير علامة
natural_featureإلى موضع طبيعي بارز. - يشير
airportإلى مطار. - تشير علامة
parkإلى متنزه مُعنون. - تشير علامة
point_of_interestإلى نقطة اهتمام مُعنونة. وعادةً ما تكون "نقاط الاهتمام" هذه كيانات محلية بارزة لا تلائم بسهولة فئة أخرى، مثل "مبنى إمباير ستيت" أو "برج إيفل".
وتشير قائمة فارغة من الأنواع إلى عدم وجود أنواع معروفة لمكوّن العنوان المحدد، على سبيل المثال، Lieu-dit في فرنسا.
بالإضافة إلى ما سبق، قد تتضمن مكونات العنوان الأنواع المذكورة هنا. هذه القائمة ليست شاملة، وتخضع للتغيير.
- يشير
floorإلى طابق عنوان المبنى. - يشير
establishmentعادةً إلى مكان لم يتم تصنيفه بعد. - تشير السمة
landmarkإلى مكان قريب يتم استخدامه كمرجع للمساعدة في التنقّل. - تشير علامة
point_of_interestإلى نقطة اهتمام مُعنونة. - تشير علامة
parkingإلى موقف أو موقف للسيارات. - يشير
post_boxإلى مربع بريدي معين. - تشير السمة
postal_townإلى مجموعة من المناطق الجغرافية، مثلlocalityوsublocality، وتُستخدَم في العناوين البريدية في بعض البلدان. - يشير
roomإلى غرفة عنوان المبنى. - يشير
street_numberإلى رقم الشارع الدقيق. - تشير السمات
bus_stationوtrain_stationوtransit_stationإلى الموقع الجغرافي لحافلة أو قطار أو محطة نقل عام.
انحياز إطار العرض
في طلب الترميز الجغرافي، يمكنك توجيه خدمة الترميز الجغرافي لتفضيل النتائج ضمن إطار عرض معيّن (يُشار إليه بمربّع الإحاطة). ويمكنك إجراء ذلك ضمن عنوان URL للطلب من خلال ضبط المَعلمة bounds.
تحدد المعلمة bounds إحداثيات خطوط العرض/الطول
للزوايا من الجنوب الغربي والشمال الشرقي من مربع الإحاطة باستخدام رمز أنبوب (|) لفصل الإحداثيات.
على سبيل المثال، يؤدي الترميز الجغرافي لكلمة "واشنطن" بشكل عام إلى عرض ولاية "واشنطن" في الولايات المتحدة:
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
الرد:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
ومع ذلك، تؤدي إضافة وسيطة bounds تحدّد مربع الإحاطة حول الجزء الشمالي الشرقي من الولايات المتحدة إلى ظهور هذه الخاصية جغرافيًا في مدينة واشنطن العاصمة:
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
الرد:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
انحياز المنطقة
في طلب الترميز الجغرافي، يمكنك توجيه خدمة الترميز الجغرافي لعرض نتائج منحازة لمنطقة معينة باستخدام المعلمة region. تأخذ هذه المعلمة وسيطة ccTLD (نطاق المستوى الأعلى لرمز البلد) لتحديد انحياز المنطقة. وتتطابق معظم رموز ccTLD
مع رموز ISO 3166-1، مع بعض الاستثناءات البارزة. على سبيل المثال، رمز نطاق ccTLD للمملكة المتحدة هو "uk" (.co.uk) بينما رمز ISO 3166-1 هو "gb"
(من الناحية الفنية للكيانات التابعة لـ "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").
يمكن انحياز نتائج الترميز الجغرافي لكل نطاق تم فيه إطلاق تطبيق "خرائط Google" الرئيسي رسميًا. يُرجى ملاحظة أن الانحياز يُفضّل نتائج نطاق معيّن فقط، وإذا كانت هناك نتائج أكثر صلة خارج هذا النطاق، قد يتم تضمينها.
على سبيل المثال، يعرض الموقع الجغرافي لـ "توليدو" هذه النتيجة، حيث إنّ النطاق التلقائي لواجهة برمجة تطبيقات الترميز الجغرافي مضبوط على الولايات المتحدة. الطلب:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
الرد:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
سيؤدي طلب الترميز الجغرافي لـ "توليدو" مع region=es (إسبانيا) إلى عرض المدينة الإسبانية.
الطلب:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
الرد:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Toledo",
"short_name" : "TO",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
تصفية المكونات
في استجابة الترميز الجغرافي، يمكن لواجهة برمجة تطبيقات الترميز الجغرافي عرض نتائج العناوين التي تقتصر على منطقة معينة. يمكنك تحديد القيد باستخدام
الفلتر components. يتألّف الفلتر من قائمة تتضمّن
component:value أزواج مفصولة بشرطة (|).
تتوافق قيم الفلاتر مع الطرق الصحيحة للتصحيح الإملائي والتطابق الجزئي مثل طلبات الترميز الجغرافي الأخرى. إذا عثر برنامج الترميز الجغرافي على تطابق جزئي لفلتر مكوّن، ستحتوي الاستجابة على الحقل partial_match.
تشمل components التي يمكن تصفيتها ما يلي:
postal_codeيطابقpostal_codeوpostal_code_prefix.- يتطابق
countryمع اسم بلد أو رمز بلد مكوّن من حرفين ISO 3166-1. تتبع واجهة برمجة التطبيقات معيار ISO لتحديد البلدان، وتعمل الفلترة بشكل أفضل عند استخدام رمز ISO المقابل للبلد.
قد يتم استخدام components التالية للتأثير في النتائج، ولكن لن يتم فرضها:
- يطابق
routeالاسم الطويل أو القصير لمسار. localityيتطابق مع نوعَين (locality) وsublocality.administrative_areaتتطابق مع جميع مستوياتadministrative_area.
ملاحظات حول تصفية المكوِّنات:
- يجب عدم تكرار فلاتر المكوّنات هذه في الطلبات، وإلا ستعرض واجهة برمجة التطبيقات
Invalid_request:countryوpostal_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"
}