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

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

إذا كان عنوان إرسال الفواتير في المنطقة الاقتصادية الأوروبية، فاعتبارًا من 8 يوليو 2025، ستسري "بنود خدمة منصة خرائط Google في المنطقة الاقتصادية الأوروبية" على استخدامك للخدمات. تختلف الوظائف حسب المنطقة. مزيد من المعلومات.

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

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

• رقم تعريف المكان لل عنوان
• رموز Plus Codes للعنوان
• تفاصيل العنوان

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

تتيح Geocoding API v4 بروتوكول 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. لمزيد من المعلومات، يُرجى الاطّلاع على جدولَي أنواع الأماكن A وB.
  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، ستستخدِم واجهة برمجة التطبيقات اللغة en تلقائيًا. إذا حدّدت رمز لغة غير صالح، ستعرض واجهة برمجة التطبيقات الخطأ INVALID_ARGUMENT
  • تبذل واجهة برمجة التطبيقات قصارى جهدها لتقديم عنوان شارع يمكن قراءته لـ لكل من المستخدم والسكان المحليين. لتحقيق هذا الهدف، تعرض واجهة برمجة التطبيقات عناوين الشوارع باللغة المحلية، مع نقلها إلى نص يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. يتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكوّنات العنوان باللغة نفسها، والتي يتم اختيارها من المكوّن الأول.
  • إذا لم يكن الاسم متاحًا باللغة المفضّلة، تستخدِم واجهة برمجة التطبيقات أقرب نتيجة مطابقة.
  • تؤثّر اللغة المفضّلة بشكل طفيف في مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، والترتيب الذي يتم عرضها به. يفسّر برنامج الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في لغة معيّنة ولكن ليس في لغة أخرى.

• regionCode

  رمز المنطقة كقيمة رمز CLDR مكوّنة من حرفَين لا توجد قيمة تلقائية. تتطابق معظم رموز CLDR مع رموز ISO 3166-1.

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

• granularity

  إعدادات قراءة واحدة أو أكثر للموقع الجغرافي، يتم تحديدها كمَعلمات طلب بحث منفصلة، كما هو محدّد في 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"
      },
      ...
    ]
  }

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

  ملاحظة مهمة: يُعدّ إخفاء الحقول ممارسة تصميم جيدة لضمان عدم طلب بيانات غير ضرورية، ما يساعد في تجنُّب وقت المعالجة غير الضروري.