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