يشير مصطلح الترميز الجغرافي بشكل عام إلى ترجمة عنوان يمكن للإنسان قراءته إلى موقع على الخريطة. تُعرف عملية تنفيذ العكس، أي ترجمة موقع على الخريطة إلى عنوان يمكن للإنسان قراءته، باسم الترميز الجغرافي العكسي.
عكس طلبات الترميز الجغرافي
المعلمات المطلوبة
latlng
: إحداثيات خط العرض وخط الطول التي تحدد الموقع الجغرافي الذي تريد الحصول على أقرب عنوان إليه سهل القراءة للمستخدمkey
— مفتاح واجهة برمجة التطبيقات لتطبيقك ويحدِّد هذا المفتاح تطبيقك لأغراض إدارة الحصص. تعرَّف على كيفية الحصول على مفتاح.
المعلمات الاختيارية
في ما يلي المعلمات الاختيارية التي يمكنك تضمينها في طلب ترميز جغرافي عكسي:
language
: اللغة التي سيتم عرض النتائج بها- اطّلِع على قائمة اللغات المتاحة. يعدّل محرّك بحث Google في كثير من الأحيان اللغات المتاحة، لذا قد لا تكون هذه القائمة شاملة.
- إذا لم يتم تقديم
language
، يحاول أداة الترميز الجغرافي استخدام اللغة المفضّلة كما هو محدّد في عنوانAccept-Language
، أو اللغة الأم للنطاق الذي يتم إرسال الطلب منه. - ويبذل جهاز الترميز الجغرافي قصارى جهده لتوفير عنوان شارع يمكن لكل من المستخدم والسكان المحليين قراءته. ولتحقيق هذا الهدف، يتم عرض عناوين الشوارع باللغة المحلية، وتحويلها صوتيًا إلى نص برمجي يمكن للمستخدم قراءته عند الضرورة، مع ملاحظة اللغة المفضَّلة. يتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكوّنات العنوان باللغة نفسها التي يتم اختيارها من العنصر الأول.
- إذا لم يكن الاسم متاحًا باللغة المفضلة، يستخدم رمز الموقع الجغرافي أقرب تطابق.
region
: تمثّل هذه السمة رمز المنطقة، ويتم تحديده على أنّه نطاق مستوى أعلى يتم ترميزه حسب البلد (ccTLD) ("نطاق المستوى الأعلى") المكوّن من حرفَين. ويمكن أن تؤثر المَعلمة أيضًا في النتائج استنادًا إلى القانون الساري.result_type
- فلتر لنوع عنوان واحد أو أكثر، يفصل بينها الشرطة الرأسية (|
). إذا كانت المعلمة تحتوي على أنواع عناوين متعددة، ستعرض واجهة برمجة التطبيقات جميع العناوين التي تطابق أيًّا من الأنواع. ملاحظة حول المعالجة: لا restrict المَعلمةresult_type
عملية البحث بأنواع العناوين المحدّدة. بدلاً من ذلك، تعملresult_type
كفلتر ما بعد البحث: تجلب واجهة برمجة التطبيقات جميع النتائج إلىlatlng
المحدّد، ثم تتجاهل تلك النتائج التي لا تتطابق مع أنواع العناوين المحدّدة. يمكن استخدام القيم التالية:- تشير السمة
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
إلى نقطة اهتمام مسماة. وفي العادة، تكون "نقاط الاهتمام" هذه كيانات محلية بارزة لا تتناسب بسهولة مع فئة أخرى، مثل "مبنى إمباير ستيت" أو "برج إيفل".
- تشير السمة
location_type
- فلتر لنوع واحد أو أكثر من أنواع المواقع الجغرافية، مفصولاً بشرطة (|
). إذا كانت المعلَمة تحتوي على عدة أنواع من المواقع الجغرافية، ستعرض واجهة برمجة التطبيقات جميع العناوين التي تطابق أيًّا من الأنواع. ملاحظة حول المعالجة: لا restrict المَعلمة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
داخل استجابة الترميز الجغرافي على رمز Plus Codes الذي
يقرّب على أفضل نحو خط العرض وخط الطول المطلوبَين.
بالإضافة إلى ذلك، يحتوي مصفوفة نتائج JSON في معظم الحالات على نتيجة ترميز جغرافي كاملة من النوع plus_code
وعنوان يحتوي على رمز علامة الجمع. من المضمون أن تكون المسافة بين رمز Plus Codes ونقطة الطلب التي تم فك ترميزها أقل من 10 أمتار.