الترميز الجغرافي العكسي لموقع

عكس الترميز الجغرافي هو عملية تحويل الموقع الجغرافي على الخريطة إلى عنوان يمكن للمستخدم قراءته. تمثّل الموقع الجغرافي على الخريطة من خلال إحداثيات خط العرض وخط الطول للموقع الجغرافي.

عند عكس الترميز الجغرافي لموقع جغرافي، يتضمّن الردّ ما يلي:

• معرّف المكان الخاص بالعنوان
• رموز Plus Codes الخاصة بالعنوان
• تفاصيل العنوان

تعرض واجهة برمجة التطبيقات هذه أنواعًا مختلفة من العناوين، بدءًا من عنوان الشارع الأكثر تحديدًا إلى الكيانات السياسية الأقل تحديدًا، مثل الأحياء والمدن والمقاطعات والولايات. يكون العنوان الأكثر دقة هو النتيجة الأولى بشكل عام. إذا أردت مطابقة نوع معيّن من العناوين، استخدِم المَعلمة types.

طلب عكس الترميز الجغرافي

طلب عكس الترميز الجغرافي هو طلب استرداد بيانات باستخدام GET. يمكنك تحديد الموقع الجغرافي كسلسلة غير منظَّمة:

https://geocode.googleapis.com/v4/geocode/location/LATITUDE,LONGITUDE

أو كمجموعة منظَّمة من إحداثيات خطوط الطول والعرض ممثَّلة بمَعلمات طلب البحث:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

عادةً ما تستخدم التنسيق المنظَّم عند معالجة مكوّنات الموقع الجغرافي التي تم التقاطها في نموذج HTML.

مرِّر جميع المَعلمات الأخرى كمَعلمات عنوان URL أو، بالنسبة إلى مَعلمات مثل مفتاح واجهة برمجة التطبيقات أو قناع الحقل، في العناوين كجزء من طلب استرداد بيانات باستخدام GET. على سبيل المثال:

تمرير سلسلة موقع جغرافي غير منظَّمة

الموقع الجغرافي غير المنظَّم هو موقع جغرافي منسَّق كسلسلة مفصولة بفواصل تتضمّن إحداثيات خطوط الطول والعرض:

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=API_KEY

أو في أمر curl:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"

تمرير موقع جغرافي منظَّم

حدِّد الموقع الجغرافي المنظَّم باستخدام مَعلمة طلب البحث location، من النوع LatLng. يتيح لك العنصر LatLng تحديد خطوط الطول والعرض كمعلَمات طلب بحث منفصلة:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

استخدام OAuth لتقديم طلب

تتيح الإصدار 4 من Geocoding API استخدام OAuth 2.0 للمصادقة. لاستخدام OAuth مع Geocoding API، يجب منح رمز OAuth المميز النطاق الصحيح. تتيح Geocoding API النطاقات التالية لاستخدامها مع عكس الترميز الجغرافي:

• https://www.googleapis.com/auth/maps-platform.geocode — تُستخدَم مع جميع طرق Geocoding API.
• https://www.googleapis.com/auth/maps-platform.geocode.location — يُستخدَم مع GeocodeLocation فقط لعكس الترميز الجغرافي.

يمكنك أيضًا استخدام النطاق العام https://www.googleapis.com/auth/cloud-platform لجميع طرق Geocoding API. يكون هذا النطاق مفيدًا أثناء التطوير، ولكن ليس في مرحلة الإنتاج، لأنّه نطاق عام يتيح الوصول إلى جميع الطرق.

لمزيد من المعلومات والأمثلة، يُرجى الاطّلاع على استخدام OAuth.

ردّ عكس الترميز الجغرافي

يعرض عكس الترميز الجغرافي عنصر GeocodeLocationResponse يحتوي على ما يلي:

• تمثّل مصفوفة results كائنات GeocodeResult التي تمثّل المكان.

  تتضمّن الردود من Geocoding API مصفوفات types في موضعَين رئيسيَّين ضمن GeocodeResult:

  1. GeocodeResult.types: يشير هذا الصفيف إلى الأنواع الإجمالية للنتيجة. يتم استخلاص القيم المحتملة من الجدول A والجدول B في صفحة "أنواع الأماكن (جديد)".
  2. GeocodeResult.addressComponents[].types: يحتوي كل مكوّن من مكوّنات العنوان على صفيف types يشير إلى نوع هذا الجزء المحدّد من العنوان. يتم استخلاص هذه القيم من جدول أنواع العناوين وأنواع مكوّنات العناوين في صفحة "أنواع الأماكن (جديد)".

  يعرض برنامج الترميز الجغرافي العكسي أكثر من نتيجة واحدة في مصفوفة results. ولا تقتصر النتائج على العناوين البريدية، بل تشمل أي طريقة لتسمية موقع جغرافي. على سبيل المثال، عند الترميز الجغرافي لنقطة في مدينة شيكاغو، يمكن الإشارة إلى النقطة المرمّزة جغرافيًا كعنوان شارع أو كمدينة (شيكاغو) أو كولاية (إلينوي) أو كبلد (الولايات المتحدة). كلها "عناوين" لبرنامج الترميز الجغرافي. تعرض أداة الترميز الجغرافي العكسي أيًا من هذه الأنواع كنتائج صالحة.

• يحتوي الحقل plusCode، من النوع PlusCode، على رمز Plus Code الذي يقدّم أفضل تقريب لخط العرض وخط الطول في الطلب. بالإضافة إلى ذلك، يحتوي كل عنصر من عناصر مصفوفة results على رمز Plus Code. المسافة بين رمز Plus Code الذي تم فك ترميزه ونقطة الطلب أقل من 10 أمتار.

  ملاحظة: لا تعرض واجهة برمجة التطبيقات رموز Plus Codes دائمًا.

يكون عنصر JSON الكامل بالشكل التالي:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "establishment",
        "point_of_interest"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

المعلمات المطلوبة

• الموقع

  تمثّل هذه السمة إحداثيات خطوط الطول والعرض التي تحدّد الموقع الجغرافي الذي تريد الحصول على أقرب عنوان إليه يمكن قراءته.

المعلمات الاختيارية

• languageCode

  اللغة التي سيتم عرض النتائج بها

  • اطّلِع على قائمة اللغات المتاحة. يُجري محرّك بحث Google تعديلات على اللغات المتوافقة بشكل متكرّر، لذا قد لا تكون هذه القائمة شاملة.
  • إذا لم يتم توفير languageCode، تضبط واجهة برمجة التطبيقات القيمة التلقائية على en. إذا حدّدت رمز لغة غير صالح، ستعرض واجهة برمجة التطبيقات رسالة الخطأ INVALID_ARGUMENT.
  • تبذل واجهة برمجة التطبيقات قصارى جهدها لتوفير عنوان شارع يمكن قراءته من قِبل المستخدمين والسكان المحليين. لتحقيق هذا الهدف، تعرض الخدمة عناوين الشوارع باللغة المحلية، مع ترجمتها إلى نص يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكونات العنوان باللغة نفسها، والتي يتم اختيارها من المكون الأول.
  • إذا لم يتوفّر اسم باللغة المفضّلة، تستخدم واجهة برمجة التطبيقات أقرب نتيجة مطابِقة.
  • للغة المفضّلة تأثير بسيط على مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، وعلى ترتيب عرضها. يفسّر برنامج الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في لغة ما ولكن ليس في لغة أخرى.

• regionCode

  تمثّل هذه السمة رمز المنطقة كقيمة رمز CLDR مكوّن من حرفَين، ولا تتضمّن قيمة تلقائية. تتطابق معظم رموز CLDR مع رموز ISO 3166-1.

  عند الترميز الجغرافي لعنوان، أي الترميز الجغرافي المباشر، يمكن أن تؤثر هذه المَعلمة في النتائج التي تعرضها الخدمة في المنطقة المحدّدة، ولكن لا يمكنها حصرها بالكامل. وعند الترميز الجغرافي لموقع جغرافي أو مكان، أي الترميز الجغرافي العكسي أو الترميز الجغرافي للمكان، يمكن استخدام هذه المَعلمة لتنسيق العنوان. وفي جميع الحالات، يمكن أن تؤثر هذه المَعلمة في النتائج استنادًا إلى القانون الساري.

• مستوى التفاصيل

  مستوى دقة واحد أو أكثر للموقع الجغرافي، يتم تحديده كمعلمات طلب بحث منفصلة، كما هو محدّد في Granularity. في حال تحديد مَعلمات granularity متعددة، تعرض واجهة برمجة التطبيقات جميع العناوين التي تتطابق مع أي من مستويات الدقة.

  لا يؤدي المَعلمة granularity إلى حصر البحث في مستويات التفاصيل المحدّدة للموقع الجغرافي، بل تعمل granularity كفلتر بعد البحث، إذ يستردّ واجهة برمجة التطبيقات جميع النتائج الخاصة بـ location المحدّدة، ثم يتجاهل النتائج التي لا تتطابق مع مستويات التفاصيل المحدّدة للموقع الجغرافي.

  إذا حدّدت كلاً من types وgranularity، ستعرض واجهة برمجة التطبيقات النتائج المطابقة لكليهما فقط. على سبيل المثال:

  https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

• الأنواع

  نوع واحد أو أكثر من أنواع العناوين، يتم تحديده كمعلَمات طلب بحث منفصلة. يتم استخلاص القيم المحتملة من جدول أنواع العناوين وأنواع عناصر العناوين في صفحة "أنواع الأماكن (جديد)". إذا حدّدت مَعلمات types متعددة، تعرض واجهة برمجة التطبيقات جميع العناوين التي تتطابق مع أي من الأنواع.

  لا يؤدي المَعلمة types إلى حصر البحث على أنواع العناوين المحدّدة، بل تعمل types كفلتر بعد البحث. تستردّ واجهة برمجة التطبيقات جميع النتائج الخاصة بالموقع الجغرافي المحدّد، ثم تتجاهل النتائج التي لا تتطابق مع أنواع العناوين المحدّدة.

  إذا حدّدت كلاً من types وgranularity، ستعرض واجهة برمجة التطبيقات النتائج المطابقة لكليهما فقط. على سبيل المثال:

  https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

• FieldMask

  أنشئ قناع حقل الاستجابة لتحديد الحقول التي سيتم عرضها في الاستجابة. مرِّر قناع حقل الاستجابة إلى الطريقة باستخدام مَعلمة عنوان URL $fields أو fields، أو باستخدام عنوان HTTP X-Goog-FieldMask. على سبيل المثال، سيعرض الطلب أدناه الحقول placeID فقط من الاستجابة.

  curl -X GET -H 'Content-Type: application/json' \
  -H 'X-Goog-FieldMask: results.placeId' \
  -H "X-Goog-Api-Key: API_KEY" \
  "https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
  

  الردّ هو:

  {
    "results": [
      {
        "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
      },
      {
        "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
      },
      {
        "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
      },
      {
        "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
      },
      ...
    ]
  }

  راجِع مقالة اختيار الحقول التي سيتم عرضها لمزيد من التفاصيل.