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

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

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

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

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

طلب الترميز الجغرافي للمكان هو طلب 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 لتقديم طلب

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

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