يشير مصطلح الترميز الجغرافي بشكل عام إلى تحويل عنوان يمكن قراءته إلى موقع جغرافي على الخريطة. وتُعرف عملية إجراء العكس، أي ترجمة موقع جغرافي على الخريطة إلى عنوان يمكن قراءته، باسم الترميز الجغرافي العكسي.
طلبات عكس الترميز الجغرافي
المعلمات المطلوبة
latlng
— إحداثيات خطوط الطول والعرض التي تحدّد الموقع الجغرافي الذي تريد الحصول على أقرب عنوان إليه يمكن قراءته.- استبدِل
key
بمفتاح واجهة برمجة التطبيقات لتطبيقك. يحدّد هذا المفتاح تطبيقك لأغراض إدارة الحصة. تعرَّف على كيفية الحصول على مفتاح.
المعلمات الاختيارية
في ما يلي المَعلمات الاختيارية التي يمكنك تضمينها في طلب ترميز جغرافي عكسي:
language
: هي اللغة التي سيتم عرض النتائج بها.- اطّلِع على قائمة اللغات المتاحة. تُحدّث Google اللغات المتوافقة بشكل متكرر، لذا قد لا تكون هذه القائمة شاملة.
- في حال عدم توفير
language
، يحاول برنامج الترميز الجغرافي استخدام اللغة المفضّلة كما هو محدّد في العنوانAccept-Language
، أو اللغة الأصلية للنطاق الذي يتم إرسال الطلب منه. - يبذل برنامج الترميز الجغرافي قصارى جهده لتقديم عنوان شارع يمكن قراءته من قِبل المستخدمين والسكان المحليين. لتحقيق هذا الهدف، تعرض الخدمة عناوين الشوارع باللغة المحلية، مع ترجمتها إلى نص يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكوّنات العنوان باللغة نفسها، التي يتم اختيارها من المكوّن الأول.
- إذا لم يتوفّر اسم باللغة المفضّلة، سيستخدم برنامج الترميز الجغرافي أقرب نتيجة مطابقة.
- استبدِل
region
برمز المنطقة المحدّد كقيمة من حرفين لنطاق المستوى الأعلى لرمز البلد. يمكن أن تؤثّر المَعلمة أيضًا في النتائج استنادًا إلى القانون الساري. result_type
: فلتر لنوع واحد أو أكثر من أنواع العناوين، مفصولة بعلامة الشرطة العمودية (|
). إذا كانت المَعلمة تحتوي على أنواع عناوين متعددة، تعرض واجهة برمجة التطبيقات جميع العناوين التي تتطابق مع أي من الأنواع. ملاحظة حول المعالجة: لا تعمل المَعلمةresult_type
على حصر البحث في أنواع العناوين المحدّدة. بل إنّresult_type
يعمل كفلتر بعد البحث: تسترد واجهة برمجة التطبيقات جميع النتائج الخاصة بـlatlng
المحدّد، ثم تتجاهل النتائج التي لا تتطابق مع أنواع العناوين المحدّدة. القيم التالية متاحة:أنواع العناوين وأنواع مكونات العناوين
تشير مصفوفة
types
في نصGeocodeResult
ضمن الاستجابة إلى نوع العنوان. تشمل أمثلة أنواع العناوين عنوان شارع أو بلدًا أو كيانًا سياسيًا. تشير مصفوفةtypes
في حقلAddressComponents
ضمن نصGeocodeResult
إلى نوع كل جزء من العنوان. وتشمل الأمثلة رقم الشارع أو البلد.قد تتضمّن العناوين أنواعًا متعددة. يمكن اعتبار الأنواع "علامات". على سبيل المثال، يتم تصنيف العديد من المدن باستخدام النوعَين
political
وlocality
.تتوفّر الأنواع التالية ويتم عرضها في كل من مصفوفة نوع العنوان ومصفوفة نوع عنصر العنوان:
نوع العنوان الوصف street_address
تمثّل هذه السمة عنوان الشارع الدقيق. route
طريق مسمّى (مثل "الطريق السريع 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 في فرنسا).
location_type
: فلتر لنوع واحد أو أكثر من أنواع المواقع الجغرافية، مفصولة بعلامة الشرطة العمودية (|
). إذا كانت المَعلمة تحتوي على أنواع متعددة من المواقع الجغرافية، تعرض واجهة برمجة التطبيقات جميع العناوين التي تتطابق مع أي من الأنواع. ملاحظة حول المعالجة: لا تؤدي المَعلمةlocation_type
إلى حصر البحث في أنواع المواقع الجغرافية المحدّدة. بدلاً من ذلك، تعمل السمةlocation_type
كفلتر بعد البحث: تسترد واجهة برمجة التطبيقات جميع النتائج الخاصة بـlatlng
المحدّدة، ثم تتجاهل النتائج التي لا تتطابق مع أنواع المواقع الجغرافية المحدّدة. في ما يلي القيم المتوافقة:- تعرض السمة
"ROOFTOP"
العناوين التي تتوفّر لدى Google معلومات دقيقة عن موقعها الجغرافي تصل إلى مستوى دقة عنوان الشارع. - تعرض
"RANGE_INTERPOLATED"
العناوين التي تشير إلى تقريب (عادةً على طريق) تم استيفاؤه بين نقطتين دقيقتين (مثل التقاطعات). يشير النطاق المُستكمَل بشكل عام إلى أنّ الرموز الجغرافية الخاصة بالأسطح غير متاحة لعنوان شارع. - تعرض
"GEOMETRIC_CENTER"
المراكز الهندسية فقط لموقع جغرافي، مثل خط متعدد الأضلاع (على سبيل المثال، شارع) أو مضلّع (منطقة). - تعرض
"APPROXIMATE"
العناوين التي تم تصنيفها على أنّها تقريبية فقط.
- تعرض السمة
extra_computations
: استخدِم هذه المَعلمة لتحديد الميزات الإضافية التالية في الرد:ADDRESS_DESCRIPTORS
— اطّلِع على واصفات العناوين لمزيد من التفاصيل.BUILDING_AND_ENTRANCES
— يمكنك الاطّلاع على المداخل والمخططات التفصيلية للمباني لمزيد من التفاصيل.
extra_computations
في الطلب لكل ميزة، على سبيل المثال:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
في حال توفّر فلترَي 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 Codes
يحتوي الحقل plus_code
ضمن استجابة الترميز الجغرافي على رمز موقع مفتوح يقدّم أفضل تقريب لخط العرض وخط الطول المطلوبَين.
بالإضافة إلى ذلك، تحتوي مصفوفة نتائج JSON في معظم الحالات على نتيجة Geocoding كاملة تتضمّن نوع plus_code
وعنوانًا يحتوي على رمز
زائد. من المفترض أن تكون المسافة بين رمز Plus Code الذي تم فك ترميزه ونقطة الطلب أقل من 10 أمتار.