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

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

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

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

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

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

https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?key=API_KEY

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"

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

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

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

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

تعرض ميزة "الترميز الجغرافي للمكان" عنصر GeocodeResult يمثّل المكان الذي يتطابق مع رقم تعريف المكان.

تتضمّن ردود Geocoding API مصفوفات types في موضعَين رئيسيَّين ضمن GeocodeResult:

1. GeocodeResult.types: تشير هذه المصفوفة إلى النوع أو الأنواع العامة للنتيجة. يتم استخلاص القيم المحتمَلة من أنواع الأماكن التي تستخدمها Places API. لمزيد من المعلومات، يُرجى الاطّلاع على جدولَي أنواع الأماكن A وB.
2. GeocodeResult.addressComponents[].types: يحتوي كل مكوّن من مكوّنات العنوان على مصفوفة types تشير إلى نوع هذا الجزء المحدّد من العنوان. يتم استخلاص هذه القيم من جدول أنواع العناوين وأنواع مكوّنات العنوان الذي تستخدمه Places API.

يكون عنصر 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 APIs الأخرى. على سبيل المثال، يمكنك استخدام placeID الذي تعرضه Roads API للحصول على عنوان لنقطة تم ضبطها. لمزيد من المعلومات عن أرقام تعريف الأماكن ، يُرجى الاطّلاع على أرقام تعريف الأماكن.

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

• languageCode

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

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

• regionCode

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

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

• FieldMask

  يمكنك إنشاء قناع حقول للرد لتحديد الحقول التي سيتم عرضها في الرد. يمكنك تمرير قناع حقول الرد إلى الطريقة باستخدام مَعلمة عنوان URL $fields أو fields، أو باستخدام عنوان HTTP X-Goog-FieldMask. على سبيل المثال، لن يعرض الطلب أدناه سوى حقل formattedAddress في الرد.

  curl -X GET -H 'Content-Type: application/json' \
  -H 'X-Goog-FieldMask: formattedAddress' \
  -H "X-Goog-Api-Key: API_KEY" \
  "https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
  

  الرد هو:

  {
    "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA"
  }

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