تبلغ الحصة التلقائية لطُرق Geocoding API v4‏ 25 طلب بحث في الثانية (QPS). للحصول على معلومات حول طلب حصة أعلى، يُرجى الاطّلاع على عرض الحصص وإدارتها واختيار Geocoding API كخدمة.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

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

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

رقم تعريف المكان الخاص بالموقع الجغرافي
إحداثيات خط العرض وخط الطول للموقع الجغرافي
رمز 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. لا تحلّل عملية الترميز الجغرافي للعناوين إحداثيات خطوط الطول والعرض أو السلاسل الأخرى غير المنظَّمة التي لا تمثّل عنوانًا أو رمز Plus Codes. لا تتوافق الطلبات التي تستخدم سلاسل من هذا النوع، وقد تؤدي إلى ظهور ردود تتضمّن أخطاء أو سلوك غير محدّد. في ما يلي أمثلة على طلبات البحث غير المتوافقة:

نوع طلب البحث	مثال
إحداثيات خط العرض وخط الطول استخدِم عكس الترميز الجغرافي بدلاً من ذلك.	"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:

GeocodeResult.types: تشير هذه المصفوفة إلى الأنواع العامة للنتيجة. يتم استخلاص القيم المحتملة من الجدول أ والجدول ب في صفحة "أنواع الأماكن (جديد)".
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 الذي تريد ترميزه جغرافيًا. ملاحظة: لا تحلّل عملية الترميز الجغرافي للعناوين إحداثيات خطوط الطول والعرض، أو السلاسل غير المنظَّمة الأخرى التي لا تمثّل عنوانًا أو رمز Plus Codes. راجِع تمرير سلسلة عنوان غير منظَّمة للاطّلاع على مزيد من التفاصيل والأمثلة حول طلبات البحث غير المتوافقة. يجب تحديد العناوين وفقًا للتنسيق الذي تستخدمه خدمة البريد الوطنية في البلد المعني. يجب تجنُّب إضافة عناصر أخرى إلى العنوان، مثل أسماء الأنشطة التجارية وأرقام الوحدات أو الأجنحة أو الطوابق. يجب أن تكون عناصر عنوان الشارع محدّدة بمسافات ومرمّزة في عنوان 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. يعمل هذا الموقع الجغرافي كعامل تحيّز، ما يعني أنّه يمكن عرض نتائج حول الموقع الجغرافي المحدّد، بما في ذلك النتائج القريبة من المنطقة ولكن خارجها.

ملاحظة: يمكن إلغاء المَعلمة locationBias إذا كان العنوان المطلوب يتضمّن موقعًا جغرافيًا صريحًا، مثل Barcelona, Spain. في هذه الحالة، يتم تجاهل locationBias.

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

يُعدّ إطار العرض منطقة مغلقة، ما يعني أنّه يشمل حدوده. يجب أن تتراوح حدود خط العرض بين 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