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

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

الترميز الجغرافي هو عملية تحويل عنوان إلى موقع جغرافي على الخريطة. عند ترميز عنوان جغرافيًا، يتضمّن الرد ما يلي:

  • رقم تعريف المكان الخاص بالموقع الجغرافي
  • إحداثيات خط العرض وخط الطول للموقع الجغرافي
  • رمز Plus Codes للموقع الجغرافي
  • تفاصيل العنوان الموسَّعة

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

طلب الترميز الجغرافي هو طلب استرداد بيانات باستخدام GET عبر HTTP. يمكنك تحديد العنوان كسلسلة غير منظَّمة:

https://geocode.googleapis.com/v4/geocode/address/ADDRESS_STRING

أو كمجموعة منظَّمة من مكوّنات العنوان ممثَّلة بمَعلمات طلب البحث:

https://geocode.googleapis.com/v4/geocode/address?STRUCTURED_ADDRESS

يتم عادةً استخدام التنسيق المنظَّم عند معالجة مكوّنات العناوين التي تم جمعها في نموذج HTML.

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

تمرير سلسلة عنوان غير منظَّمة

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

نوع طلب البحث مثال
إحداثيات خط العرض وخط الطول استخدِم الترميز الجغرافي العكسي بدلاً من ذلك. "37.422131,-122.084801"
عدد كبير جدًا من المفاهيم أو القيود، مثل أسماء أماكن أو طرق أو مدن متعددة في طلب بحث واحد "شارع ماركت في سان فرانسيسكو، مطار سان خوسيه"
عناصر العنوان البريدي غير الممثّلة على "خرائط Google" "C/O John Smith 123 Main Street"
"P.O. Box 13 San Francisco"
أسماء الأنشطة التجارية أو السلاسل أو الفئات مع المواقع الجغرافية التي لا تتوفّر فيها هذه الكيانات "Tesco بالقرب من دالاس، تكساس"
طلبات بحث غامضة تتضمّن تفسيرات متعددة "استلام الشاحن"
الأسماء القديمة التي لم يعُد يتم استخدامها "ميدلسكس، المملكة المتحدة"
العناصر أو النية غير الجغرافية المكانية "كم عدد القوارب في ميناء فينتورا؟"
الأسماء غير الرسمية أو أسماء الشهرة "The Jenga"
"The Helter Skelter"

على سبيل المثال، يجتاز المثال التالي سلسلة العنوان المشفرة بتنسيق URL "1600 Amphitheatre Parkway, Mountain View, CA":

https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY

لاحظ أنّه يتم تحويل الرمز "+" في عنوان URL إلى مسافة.

يمكنك أيضًا تقديم الطلب باستخدام أمر curl:

curl -H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

يمكن أن تحتوي العناوين على العديد من أنواع الرموز الخاصة، مثل "/" كما في "7/1 King St, Concord West". يجب ترميز "/" باستخدام ترميز URL على النحو التالي: %2F

https://geocode.googleapis.com/v4/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

مثال شائع آخر هو الرمز "#"، كما في "9500 W Bryn Mawr Ave #650, Rosemont". تشفير علامة "#" في عنوان URL على النحو التالي: %2FE:

https://geocode.googleapis.com/v4/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

في المثال التالي، يمكنك تحديد سلسلة عناوين غير منظَّمة كرمز Plus Code 849VCWC8+R4. تأكَّد من ترميز علامة "+" في عنوان URL على النحو التالي: %2B:

https://geocode.googleapis.com/v4/geocode/address/849VCWC8%2BR4?key=API_KEY

تمرير عنوان منظَّم

حدِّد عنوانًا منظَّمًا باستخدام مَعلمة طلب البحث address من النوع PostalAddress. يتيح لك العنصر PostalAddress تحديد بعض أو كل مكوّنات العنوان في الطلب كمعلمات طلب بحث فردية.

على سبيل المثال، لتحديد الرمز البريدي فقط للعنوان الذي تستخدمه PostalAddress.postalCode:

https://geocode.googleapis.com/v4/geocode/address?address.postalCode=01062&key=API_KEY

لتحديد مكوّنات عناوين متعددة، مثل مكوّنات العناوين التي يتم جمعها في نموذج HTML، استخدِم مَعلمات طلب بحث متعددة:

https://geocode.googleapis.com/v4/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View&address.administrativeArea=CA&key=API_KEY

استخدام 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.address — لا تستخدِمها إلا مع GeocodeAddress لإجراء الترميز الجغرافي الأمامي.

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

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

استجابة الترميز الجغرافي

تعرض خدمة الترميز الجغرافي عنصر GeocodeAddressResponse يحتوي على مصفوفة results من عناصر GeocodeResult. يمثّل كل عنصر GeocodeResult مكانًا واحدًا.

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

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

يكون عنصر JSON الكامل بالشكل التالي:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "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"
        },
        ...
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCWC8+R4",
        "compoundCode": "CWC8+R4 Mountain View, CA, USA"
      }
    }
  ]
}

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

  • address — عنوان الشارع أو رمز Plus Code الذي تريد تحويله إلى إحداثيات جغرافية. ملاحظة: لا يؤدي الترميز الجغرافي للعناوين إلى تحديد إحداثيات خطوط الطول والعرض، أو السلاسل الأخرى غير المنظَّمة التي لا تمثّل عنوانًا أو رمزًا بريديًا. راجِع تمرير سلسلة عنوان غير منظَّمة للاطّلاع على مزيد من التفاصيل والأمثلة على طلبات البحث غير المتوافقة. يجب تحديد العناوين وفقًا للتنسيق الذي تستخدمه خدمة البريد الوطنية في البلد المعني. يجب تجنُّب عناصر العنوان الإضافية، مثل أسماء المؤسسات وأرقام الوحدات أو الأجنحة أو الطوابق. يجب أن تكون عناصر عنوان الشارع محدّدة بمسافات ومرمّزة في عنوان URL إلى %20. على سبيل المثال، مرِّر العنوان "24 Sussex Drive Ottawa ON" على النحو التالي: 
    24%20Sussex%20Drive%20Ottawa%20ON
     يجب تنسيق رموز Plus Codes كما هو موضّح أدناه. يتم ترميز علامات الجمع في عناوين URL إلى %2B ويتم ترميز المسافات إلى %20:
    • الرمز العالمي هو رمز منطقة يتألف من 4 أحرف ورمز محلي يتألف من 6 أحرف أو أكثر. على سبيل المثال، ترميز "849VCWC8+R9" على النحو التالي: 849VCWC8%2BR9
    • الرمز المركّب هو رمز محلي يتألف من 6 أحرف أو أكثر ويتضمّن موقعًا جغرافيًا محددًا. على سبيل المثال، ترميز "CWC8+R9 Mountain View, CA, USA" على النحو CWC8%2BR9%20Mountain%20View%20CA%20USA.

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

  • locationBias

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

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

    يُعدّ إطار العرض منطقة مغلقة، ما يعني أنّه يشمل حدوده. يجب أن تتراوح حدود خط العرض بين 90- و90 درجة شاملة، ويجب أن تتراوح حدود خط الطول بين 180- و180 درجة شاملة:

    • إذا كان low = high، يتألف إطار العرض من تلك النقطة الفردية.
    • إذا كانت low.longitude > high.longitude، يكون نطاق خط الطول معكوسًا (يعبر إطار العرض خط الطول 180 درجة).
    • إذا كانت low.longitude = -180 درجة وhigh.longitude = 180 درجة، ستشمل نافذة العرض جميع خطوط الطول.
    • إذا كانت low.longitude = 180 درجة وhigh.longitude = -180 درجة، سيكون نطاق خط الطول فارغًا.
    • إذا كان low.latitude > high.latitude، يكون نطاق خطوط العرض فارغًا.

    يجب ملء كلّ من الحدّين الأدنى والأعلى، ويجب ألا يكون المربّع الممثّل فارغًا، وإلا سيحدث خطأ.

    على سبيل المثال، يحدّد سلسلة طلب البحث هذه إطار عرض يضمّ مدينة نيويورك بالكامل:

    ?locationBias.rectangle.low.latitude=40.477398&locationBias.rectangle.low.longitude=-74.259087&locationBias.rectangle.high.latitude=40.91618&locationBias.rectangle.high.longitude=-73.70018

  • languageCode

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

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

  • regionCode

    تمثّل هذه السمة رمز المنطقة كقيمة رمز CLDR مكوّن من حرفَين، ولا تتضمّن قيمة تلقائية. تتطابق معظم رموز CLDR مع رموز ISO 3166-1.

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

  • FieldMask

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

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
    الردّ هو: 
    {
  "results": [
    {
      "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc"
    }
  ]
}

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

تفضيل المواقع الجغرافية

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

على سبيل المثال، يمكن أن يؤدي طلب رمز جغرافي للعنوان "واشنطن" إلى عرض نتائج خاصة بواشنطن العاصمة وولاية واشنطن الأمريكية:

https://geocode.googleapis.com/v4/geocode/address/Washington?key=API_KEY

يكون الردّ بالتنسيق التالي:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "location": {
        "latitude": 38.9071923,
        "longitude": -77.0368707
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "bounds": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "formattedAddress": "Washington, DC, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "Washington",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "location": {
        "latitude": 47.7510741,
        "longitude": -120.7401386
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024945,
          "longitude": -116.91607109999998
        }
      },
      "bounds": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024442,
          "longitude": -116.91607109999998
        }
      },
      "formattedAddress": "Washington, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "WA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
      ...
      ],
      "types": [
        "administrative_area_level_1",
        "political"
      ]
    }
  ]
}

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

https://geocode.googleapis.com/v4/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72&locationBias.rectangle.high.latitude=43.39&locationBias.rectangle.high.longitude=-65.90&key=API_KEY

تفضيل المنطقة

في طلب الترميز الجغرافي، يمكنك توجيه خدمة الترميز الجغرافي لعرض نتائج متحيزة لمنطقة معيّنة باستخدام المَعلمة regionCode. تتلقّى هذه المَعلمة قيمة رمز CLDR مكوّنًا من حرفَين تحدّد المنطقة التي يتم التركيز عليها. معظم رموز CLDR مطابقة لرموز ISO 3166-1.

ليس هناك قيمة تلقائية لـ regionCode. على سبيل المثال، يؤدي الرمز الجغرافي الخاص بـ "توليدو" إلى عرض نتائج خاصة بالولايات المتحدة وإسبانيا:

https://geocode.googleapis.com/v4/geocode/address/Toledo?key=API_KEY

الردّ:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "location": {
        "latitude": 41.652805199999996,
        "longitude": -83.5378674
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "bounds": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "formattedAddress": "Toledo, OH, USA",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM",
      "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM",
      "location": {
        "latitude": 39.8628296,
        "longitude": -4.0273067
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "bounds": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "formattedAddress": "Toledo, España",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "administrative_area_level_4",
            "political"
          ],
          "languageCode": "es"
        },
        ...
      ],
      "types": [
        "administrative_area_level_4",
        "political"
      ]
    },
    ...
  ]
}

سيؤدي طلب الترميز الجغرافي لـ "طليطلة" مع regionCode=es (إسبانيا) إلى عرض نتائج من إسبانيا فقط:

https://geocode.googleapis.com/v4/geocode/address/Toledo?regionCode=es&key=API_KEY