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

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

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

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

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

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

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

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

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

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

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

العنوان غير المهيكل هو عنوان منسَّق كسلسلة أو رمز Plus Code. على سبيل المثال، يجتاز المثال التالي سلسلة العنوان المشفرة بعنوان URL "1600 Amphitheatre Parkway, Mountain View, CA":

https://geocode.googleapis.com/v4beta/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/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

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

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

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

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

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

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

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

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

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

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

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

https://geocode.googleapis.com/v4beta/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 مكانًا واحدًا.

يكون كائن 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.

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

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

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

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

https://geocode.googleapis.com/v4beta/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/v4beta/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/v4beta/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/v4beta/geocode/address/Toledo?regionCode=es&key=API_KEY