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

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

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

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

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

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