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

المطوّرون في المنطقة الاقتصادية الأوروبية

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

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

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

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

طلب عكس الترميز الجغرافي هو طلب HTTP 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"
    },
    ...
  ]
}

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