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

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

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

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

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

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

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

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

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

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

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

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

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

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

https://geocode.googleapis.com/v4beta/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/v4beta/geocode/location/37.4225508,-122.0846338"

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

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

https://geocode.googleapis.com/v4beta/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 التي تمثّل المكان.

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

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

يكون كائن 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/v4beta/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

  • الأنواع

    نوع واحد أو أكثر من أنواع العناوين، يتم تحديده كمعلَمات طلب بحث منفصلة في حال تحديد عدة مَعلمات types، تعرض واجهة برمجة التطبيقات جميع العناوين التي تتطابق مع أي من الأنواع.

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

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

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

    يمكن استخدام القيم التالية:

    أنواع العناوين وأنواع مكونات العناوين

    تشير مصفوفة types في نص GeocodeResult ضمن الاستجابة إلى نوع العنوان. تشمل أمثلة أنواع العناوين عنوان شارع أو بلدًا أو كيانًا سياسيًا. تشير مصفوفة types في حقل AddressComponents ضمن نص GeocodeResult إلى نوع كل جزء من العنوان. وتشمل الأمثلة رقم الشارع أو البلد.

    قد تتضمّن العناوين أنواعًا متعددة. يمكن اعتبار الأنواع "علامات". على سبيل المثال، يتم تصنيف العديد من المدن باستخدام النوعَين political وlocality.

    تتوفّر الأنواع التالية ويتم عرضها في كل من مصفوفة نوع العنوان ومصفوفة نوع عنصر العنوان:

    نوع العنوان الوصف
    street_address تمثّل هذه السمة عنوان الشارع الدقيق.
    route طريق مسمّى (مثل "الطريق السريع 101 في الولايات المتحدة")
    intersection تقاطع رئيسي، عادةً ما يكون بين طريقَين رئيسيَّين
    political كيان سياسي يشير هذا النوع عادةً إلى مضلّع تابع لإحدى الإدارات المدنية.
    country تمثّل هذه السمة الكيان السياسي الوطني، وهي عادةً أعلى نوع ترتيب يعرضه برنامج الترميز الجغرافي.
    administrative_area_level_1 تمثّل هذه السمة منطقة إدارية من الدرجة الأولى تندرج تحت مستوى البلد. داخل الولايات المتحدة، تكون هذه المستويات الإدارية هي الولايات. لا تستخدم بعض البلدان هذه المستويات الإدارية. في معظم الحالات، ستتطابق administrative_area_level_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 تمثّل هذه السمة نقطة اهتمام محدّدة الاسم. عادةً ما تكون "نقاط الاهتمام" هذه عبارة عن كيانات محلية بارزة لا يمكن تصنيفها بسهولة ضمن فئة أخرى، مثل "مبنى إمباير ستيت" أو "برج إيفل".

    تشير القائمة الفارغة من الأنواع إلى عدم توفّر أي أنواع معروفة لمكوّن العنوان المحدّد (على سبيل المثال، Lieu-dit في فرنسا).