يشير مصطلح الترميز الجغرافي بشكل عام إلى ترجمة عنوان يمكن للمستخدمين قراءته إلى موقع على الخريطة. تُعرف عملية إجراء العكس، ترجمة الموقع على الخريطة إلى عنوان يمكن قراءته، باسم الترميز الجغرافي العكسي.
عكس طلبات الترميز الجغرافي
المعلمات المطلوبة
latlng
— إحداثيات خطوط العرض وخطوط الطول التي تحدد الموقع الجغرافي الذي تريد أن يكون العنوان الأقرب إليه والذي يمكن للمستخدمين قراءته.key
— مفتاح واجهة برمجة التطبيقات للتطبيق. يحدّد هذا المفتاح تطبيقك لأغراض إدارة الحصص. تعرَّف على كيفية الحصول على مفتاح.
المعلمات الاختيارية
في ما يلي المعلمات الاختيارية التي يمكنك تضمينها في طلب الترميز الجغرافي العكسي:
language
— اللغة التي سيتم عرض النتائج بها.- راجِع قائمة اللغات المتوافقة. غالبًا ما تحدّث Google اللغات المتوافقة، لذا قد لا تكون هذه القائمة شاملة.
- إذا لم يتم تقديم
language
، يحاول برنامج الترميز الجغرافي استخدام اللغة المفضّلة على النحو المحدّد في العنوانAccept-Language
أو اللغة الأصلية للنطاق الذي يتم إرسال الطلب منه. - وتبذل أداة الترميز الجغرافي أقصى جهدها لتوفير عنوان شارع يمكن لكل من المستخدم والسكان المحليين قراءته. ولتحقيق هذا الهدف، تعرض علامة التبويب هذه عناوين الشوارع باللغة المحلية، ويتم تحويلها إلى نص برمجي يمكن للمستخدم قراءته، إذا لزم الأمر، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. ويتم عرض جميع مكوّنات العناوين باللغة نفسها التي يتم اختيارها من المكوِّن الأول.
- إذا لم يكن الاسم متوفّرًا باللغة المفضّلة، يستخدم برنامج الترميز الجغرافي التطابق الأقرب.
result_type
— فلتر من نوع واحد أو أكثر من أنواع العناوين، مفصول بينها بشرطة (|
). إذا كانت المعلمة تحتوي على أنواع عناوين متعددة، تعرض واجهة برمجة التطبيقات جميع العناوين التي تطابق أيًا من الأنواع. ملاحظة عن المعالجة: لا تقوم المعلمةresult_type
بتقييد البحث على أنواع العناوين المحددة. وبدلاً من ذلك، تعمل السمةresult_type
كفلتر بعد البحث: تجلب واجهة برمجة التطبيقات جميع النتائج للسمةlatlng
المحدّدة، ثم تتجاهل النتائج التي لا تتطابق مع أنواع العناوين المحدّدة. القيم التالية متاحة:- يشير
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
إلى نقطة اهتمام مُعنونة. وعادةً ما تكون "نقاط الاهتمام" هذه كيانات محلية بارزة لا تلائم بسهولة فئة أخرى، مثل "مبنى إمباير ستيت" أو "برج إيفل".
- يشير
location_type
— فلتر لنوع واحد أو أكثر من أنواع المواقع الجغرافية، مع الفصل بينها بخط عمودي (|
). إذا كانت المعلّمة تحتوي على أنواع مواقع جغرافية متعددة، ستعرض واجهة برمجة التطبيقات جميع العناوين التي تتطابق مع أي نوع من الأنواع. ملاحظة عن المعالجة: لا تُجري المعلّمةlocation_type
تقييدًا للبحث على أنواع المواقع الجغرافية المحدّدة. وبدلاً من ذلك، تعمل السمةlocation_type
كفلتر بعد البحث: تجلب واجهة برمجة التطبيقات جميع النتائج للسمةlatlng
المحدّدة، ثم تتجاهل النتائج التي لا تتطابق مع أنواع المواقع الجغرافية المحدّدة. تتوفّر القيم التالية:- لا تعرض
"ROOFTOP"
سوى العناوين التي يشتمل محرك بحث Google على معلومات موقعها بدقة حتى دقة عنوان الشارع. - لا تعرض
"RANGE_INTERPOLATED"
سوى العناوين التي تعكس موقعًا تقريبيًا (عادةً على طريق) في ما بين نقطتين دقيقتين (مثل التقاطعات). يشير النطاق الذي تمت إضافته بشكل عام إلى أنّ الرموز الجغرافية على السطح غير متاحة لعنوان الشارع. - تعرض
"GEOMETRIC_CENTER"
المراكز الهندسية لموقع جغرافي فقط مثل الخط المتعدد الخطوط (مثل الشارع) أو المضلّع (المنطقة). - لا تعرض
"APPROXIMATE"
سوى العناوين التي يتم تحديدها على أنها تقريبية.
- لا تعرض
وفي حال توفّر الفلترَين result_type
وlocation_type
، ستعرض واجهة برمجة التطبيقات فقط النتائج التي تتطابق مع القيمتَين result_type
وlocation_type
. إذا لم تكن أي من قيم الفلتر مقبولة، ستعرض واجهة برمجة التطبيقات ZERO_RESULTS
.
مثال على الترميز الجغرافي العكسي
يحتوي طلب البحث التالي على قيمة خط العرض/الطول لموقع في الإسكندرية:
https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY
يعرض طلب البحث أعلاه النتيجة التالية:
{
"results" : [
{
"address_components" : [
{
"long_name" : "277",
"short_name" : "277",
"types" : [ "street_number" ]
},
{
"long_name" : "Bedford Avenue",
"short_name" : "Bedford Ave",
"types" : [ "route" ]
},
{
"long_name" : "Williamsburg",
"short_name" : "Williamsburg",
"types" : [ "neighborhood", "political" ]
},
{
"long_name" : "Brooklyn",
"short_name" : "Brooklyn",
"types" : [ "sublocality", "political" ]
},
{
"long_name" : "Kings",
"short_name" : "Kings",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "New York",
"short_name" : "NY",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
},
{
"long_name" : "11211",
"short_name" : "11211",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"geometry" : {
"location" : {
"lat" : 40.714232,
"lng" : -73.9612889
},
"location_type" : "ROOFTOP",
"viewport" : {
"northeast" : {
"lat" : 40.7155809802915,
"lng" : -73.9599399197085
},
"southwest" : {
"lat" : 40.7128830197085,
"lng" : -73.96263788029151
}
}
},
"place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
"types" : [ "street_address" ]
},
... Additional <code>results[]</code> ...
لاحظ أن برنامج الترميز الجغرافي العكسي عرض أكثر من نتيجة واحدة. لا تمثل نتائج "formatted_address"
عناوين بريدية فحسب، بل هي طريقة لتسمية موقع جغرافي. على سبيل المثال، عند ترميز موقع جغرافي في مدينة شيكاغو، يمكن الإشارة إلى النقطة جغرافيًا على أنها عنوان شارع، أو كالمدينة (شيكاغو)، أو الولاية (إلينوي) أو كبلد (الولايات المتحدة). جميعها "عناوين" إلى أداة الترميز الجغرافي. وتعرض أداة الترميز العكسية
أيًا من هذه الأنواع كنتائج صالحة.
ويتطابق نظام الترميز الجغرافي العكسي مع الكيانات السياسية (البلاد والمقاطعات والمدن والأحياء) وعناوين الشوارع والرموز البريدية.
في ما يلي القائمة الكاملة لقيم formatted_address
التي يعرضها طلب البحث السابق.
{
"plus_code" : {
"compound_code" : "P27Q+MCM New York, NY, USA",
"global_code" : "87G8P27Q+MCM"
},
"results" : [
{
"formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "street_address" ]
},
{
"formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "premise" ]
},
{
"formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "establishment", "point_of_interest" ]
},
{
"formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "route" ]
},
{
"formatted_address" : "P27Q+MC New York, NY, USA",
...
"types" : [ "plus_code" ]
},
{
"formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
...
"types" : [ "neighborhood", "political" ]
},
{
"formatted_address" : "Brooklyn, NY 11211, USA",
...
"types" : [ "postal_code" ]
},
{
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
...
"types" : [ "neighborhood", "political" ]
},
{
"formatted_address" : "Kings County, Brooklyn, NY, USA",
...
"types" : [ "administrative_area_level_2", "political" ]
},
{
"formatted_address" : "Brooklyn, NY, USA",
...
"types" : [ "political", "sublocality", "sublocality_level_1" ]
},
{
"formatted_address" : "New York, NY, USA",
...
"types" : [ "locality", "political" ]
},
{
"formatted_address" : "New York, USA",
...
"types" : [ "administrative_area_level_1", "political" ]
},
{
"formatted_address" : "United States",
...
"types" : [ "country", "political" ]
}
],
"status" : "OK"
}
تعرض واجهة برمجة التطبيقات هذه أنواعًا مختلفة من العناوين، من عنوان الشارع الأكثر تحديدًا إلى الكيانات السياسية الأقل تحديدًا، مثل الأحياء والمدن والمقاطعات والولايات. العنوان الأكثر دقة هو النتيجة الأبرز بشكل عام، كما في هذه الحالة. إذا كنت تريد مطابقة نوع محدّد من العناوين، يمكنك الاطّلاع على القسم أدناه حول تقييد النتائج حسب النوع. ولهذا السبب، قد يختلف موقع النتائج بالنسبة إلى بعضها البعض.
عكس الترميز الجغرافي المفلتر حسب النوع
يوضّح المثال التالي العناوين التي تم عرضها لتتضمن فقط
العناوين التي تتضمّن نوع الموقع الجغرافي ROOFTOP
ونوع العنوان
street_address
.
https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY
ملاحظة: هذه الفلاتر صالحة فقط للترميز الجغرافي العكسي.
عكس استجابات الترميز الجغرافي
يكون تنسيق استجابة الترميز الجغرافي هو نفسه استجابة الترميز الجغرافي. راجع استجابات الترميز الجغرافي. في ما يلي شفرات الحالة الممكنة في استجابة الترميز الجغرافي.
رموز حالة الترميز الجغرافي العكسي
يحتوي الحقل "status"
ضمن كائن الاستجابة "الترميز الجغرافي" على حالة الطلب، وقد يحتوي على معلومات تصحيح الأخطاء لمساعدتك في تتبّع سبب عدم عمل ميزة الترميز الجغرافي العكسي. قد يحتوي الحقل "status"
على القيم التالية:
- تشير القيمة
"OK"
إلى عدم حدوث أخطاء وإرجاع عنوان واحد على الأقل. - تشير القيمة
"ZERO_RESULTS"
إلى أن الترميز الجغرافي العكسي كان ناجحًا، ولكن لم يتم عرض أي نتائج. وقد يحدث ذلك إذا اجتازت أداة الترميزlatlng
في موقع بعيد. - يشير
"OVER_QUERY_LIMIT"
إلى أنك تجاوزت حصتك. - تشير علامة
"REQUEST_DENIED"
إلى أنه تم رفض الطلب. قد يكون السبب أنّ الطلب يتضمّن معلَمةresult_type
أوlocation_type
ولكن لا يتضمّن مفتاح واجهة برمجة تطبيقات. - تشير السمة
"INVALID_REQUEST"
بشكل عام إلى أحد العناصر التالية:- طلب البحث (
address
أوcomponents
أوlatlng
) مفقود. - تم تقديم سمة
result_type
أوlocation_type
غير صالحة.
- طلب البحث (
- تشير علامة
"UNKNOWN_ERROR"
إلى أنّه تعذّرت معالجة الطلب بسبب خطأ في الخادم. وقد ينجح الطلب في حال إعادة المحاولة.
عكس رموز المواقع الجغرافية الإضافية
يحتوي الحقل plus_code
ضمن استجابة الترميز الجغرافي على رمز زائد
يُطابق تقريبًا خطوط الطول والعرض المطلوبة.
بالإضافة إلى ذلك، تحتوي مصفوفة نتائج JSON في معظم الحالات على نتيجة ترميز جغرافي كاملة مع نوع plus_code
وعنوان يحتوي على رمز علامة زائد. يتم ضمان المسافة بين رمز الموقع المفتوح الذي تم فك ترميزه ونقطة الطلب
لأقل من 10 أمتار.