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

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

تحدِّد أرقام تعريف الأماكن مكانًا بشكلٍ فريد في قاعدة بيانات أماكن 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: يشير هذا الصفيف إلى الأنواع الإجمالية للنتيجة. يتم استخلاص القيم المحتملة من الجدول A والجدول B في صفحة "أنواع الأماكن (جديد)".
2. GeocodeResult.addressComponents[].types: يحتوي كل مكوّن من مكوّنات العنوان على صفيف types يشير إلى نوع هذا الجزء المحدّد من العنوان. يتم استخلاص هذه القيم من جدول أنواع العناوين وأنواع مكوّنات العناوين في صفحة "أنواع الأماكن (جديد)".

يكون عنصر 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.

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

• 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"
  }

  راجِع مقالة اختيار الحقول التي سيتم عرضها لمزيد من التفاصيل.