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

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

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

• رقم تعريف المكان الخاص بالعنوان
• رموز 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: تشير هذه المصفوفة إلى الأنواع العامة للنتيجة. يتم استخلاص القيم المحتملة من أنواع الأماكن التي تستخدمها Places API. لمزيد من المعلومات، يُرجى الاطّلاع على الجدولَين "أ" و"ب" لأنواع الأماكن.
  2. GeocodeResult.addressComponents[].types: يحتوي كل مكوّن من مكوّنات العنوان على مصفوفة types تشير إلى نوع هذا الجزء المحدّد من العنوان. يتم استخلاص هذه القيم من جدول أنواع العناوين وأنواع مكوّنات العناوين الذي تستخدمه Places API.

  تعرض أداة عكس الترميز الجغرافي أكثر من نتيجة واحدة في مصفوفة 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، يتم ضبط واجهة برمجة التطبيقات تلقائيًا على اللغة المحلية ونص الموقع الجغرافي. إذا حدّدت رمز لغة غير صالح، ستعرض واجهة برمجة التطبيقات الخطأ 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"
      },
      ...
    ]
  }

  لمزيد من التفاصيل، يُرجى الاطّلاع على اختيار الحقول المطلوب عرضها.