الترميز الجغرافي للأماكن

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

تتيح لك عملية الترميز الجغرافي للأماكن استرداد عنوان من معرّف مكان.

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

طلبات الترميز الجغرافي للأماكن

طلب الترميز الجغرافي للمكان هو طلب HTTP GET بالتنسيق التالي:

https://geocode.googleapis.com/v4beta/geocode/places/PLACE_ID

حيث يحتوي PLACE_ID على معرّف المكان الخاص بالموقع الجغرافي محلّ الاهتمام.

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

https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?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/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"

استخدام 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.place — استخدِمها فقط مع GeocodePlace لترميز المواقع الجغرافية.

يمكنك أيضًا استخدام النطاق العام https://www.googleapis.com/auth/cloud-platform لجميع نقاط نهاية Geocoding API. يكون هذا النطاق مفيدًا أثناء التطوير، ولكن ليس أثناء الإنتاج، لأنّه نطاق عام يتيح الوصول إلى جميع نقاط النهاية.

لمزيد من المعلومات والأمثلة، يُرجى الاطّلاع على استخدام بروتوكول OAuth.

ردود الترميز الجغرافي للأماكن

تعرض خدمة الترميز الجغرافي للأماكن كائن GeocodeResult يمثّل المكان الذي يتطابق مع رقم تعريف المكان.

يكون كائن JSON الكامل بالشكل التالي:

{
  "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "location": {
    "latitude": 37.4220541,
    "longitude": -122.08532419999999
  },
  "granularity": "ROOFTOP",
  "viewport": {
    "low": {
      "latitude": 37.4209489697085,
      "longitude": -122.08846930000001
    },
    "high": {
      "latitude": 37.4236469302915,
      "longitude": -122.0829156
    }
  },
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  "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"
  ]
}

المعلمات المطلوبة

  • استبدِل place بمعرّف المكان الذي تريد الحصول على عنوانه المقروء. معرّف المكان هو معرّف فريد يمكن استخدامه مع واجهات برمجة تطبيقات أخرى من Google. على سبيل المثال، يمكنك استخدام placeID الذي تعرضه واجهة Roads API للحصول على عنوان نقطة تم التقاطها. لمزيد من المعلومات حول معرّفات الأماكن، يُرجى الاطّلاع على معرّفات الأماكن.

المعلمات الاختيارية

  • languageCode

    اللغة التي سيتم عرض النتائج بها

    • اطّلِع على قائمة اللغات المتاحة. تعدّل Google اللغات المتوافقة بشكل متكرر، لذا قد لا تكون هذه القائمة شاملة.
    • إذا لم يتم توفير languageCode، ستضبط واجهة برمجة التطبيقات القيمة التلقائية على en. في حال تحديد رمز لغة غير صالح، ستعرض واجهة برمجة التطبيقات الخطأ INVALID_ARGUMENT.
    • تبذل واجهة برمجة التطبيقات قصارى جهدها لتوفير عنوان شارع يمكن قراءته من قِبل المستخدمين والسكان المحليين. ولتحقيق هذا الهدف، تعرض الخدمة عناوين الشوارع باللغة المحلية، مع ترجمتها إلى نص يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكونات العنوان باللغة نفسها، والتي يتم اختيارها من المكون الأول.
    • إذا لم يتوفّر اسم باللغة المفضّلة، تستخدم واجهة برمجة التطبيقات أقرب نتيجة مطابِقة.
    • للغة المفضّلة تأثير بسيط على مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، وعلى ترتيب عرضها. يفسّر برنامج الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في لغة ما ولكن ليس في لغة أخرى.

  • regionCode

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

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