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

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

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

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

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

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

حيث يحتوي PLACE_ID على رقم تعريف المكان لموقع الاهتمام.

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

https://geocode.googleapis.com/v4/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/v4/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 يمثّل المكان المقابل لرقم تعريف المكان.

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

1. ‫GeocodeResult.types: تشير هذه المصفوفة إلى الأنواع العامة للنتيجة. يتم استخلاص القيم المحتملة من أنواع الأماكن التي تستخدمها Places API. لمزيد من المعلومات، يُرجى الاطّلاع على الجدولَين "أ" و"ب" لأنواع الأماكن.
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، يتم ضبط واجهة برمجة التطبيقات تلقائيًا على اللغة المحلية ونص الموقع الجغرافي. إذا حدّدت رمز لغة غير صالح، ستعرض واجهة برمجة التطبيقات الخطأ 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"
  }

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