إعداد Geocoding API

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

إذا كان عنوان إرسال الفواتير الخاص بك في المنطقة الاقتصادية الأوروبية، فاعتبارًا من 8 يوليو 2025، ستسري بنود خدمة Google Maps Platform في المنطقة الاقتصادية الأوروبية على استخدامك للخدمات. تختلف الوظائف حسب المنطقة. مزيد من المعلومات.

توضّح هذه المستندات الخطوات اللازمة لبدء استخدام Geocoding API.

1. الحساب والفوترة تأكَّد من استيفاء المتطلبات الأساسية.

2. تفعيل واجهة برمجة التطبيقات فعِّل واجهة برمجة التطبيقات في مشروعك على Google Cloud.

3. إجراء طلبك الأول يمكنك ضبط مفتاح واجهة برمجة التطبيقات أو OAuth لإجراء طلب بيانات مصادق من واجهة برمجة التطبيقات.

ملاحظة مهمة: يتضمّن دليل الإعداد هذا الإجراء الخاص بكل من ضبط مفتاح واجهة برمجة التطبيقات وإنشاء رمز OAuth مميز. اختَر الإجراء المناسب لبيئة النشر.

يتم تأمين منتجات منصة خرائط Google من الاستخدام غير المصرّح به من خلال إلزام طلبات واجهة برمجة التطبيقات بتضمين إما مفتاح واجهة برمجة التطبيقات أو رمز OAuth مميز.

مفتاح واجهة برمجة التطبيقات رمز OAuth مميز

إنشاء رمز OAuth مميز

تتيح Geocoding API استخدام OAuth 2.0 للمصادقة. توفّر Google سيناريوهات OAuth 2.0 الشائعة، مثل سيناريوهات خادم الويب.

توضّح هذه المستندات كيفية تمرير رمز OAuth مميز إلى طلب بيانات من واجهة برمجة التطبيقات Geocoding API في بيئة التطوير. للحصول على تعليمات حول استخدام OAuth في بيئة الإنتاج، يُرجى الاطّلاع على مقالة طرق المصادقة في Google.

ملاحظة:

على الرغم من أنّه يمكنك استخدام Google Maps APIs مباشرةً من خلال إرسال طلبات واجهة برمجة التطبيقات إلى الخادم، فإنّ مكتبات العملاء توفّر تبسيطات تقلّل بشكل كبير من مقدار الرمز البرمجي الذي عليك كتابته. توفّر خرائط Google مكتبات عملاء للعديد من لغات البرمجة، بما في ذلك Go وJava وNode.js وPython.

يُرجى الاطّلاع على Geocoding API Client Libraries للحصول على المستندات والأمثلة.

لمحة عن OAuth

هناك طرق عديدة لإنشاء رموز الوصول وإدارتها باستخدام OAuth استنادًا إلى بيئة النشر.

على سبيل المثال، يتيح نظام Google OAuth 2.0 التفاعلات بين الخادم والخادم، مثل التفاعلات بين تطبيقك وإحدى خدمات Google. في هذا السيناريو، تحتاج إلى حساب خدمة، وهو حساب ينتمي إلى تطبيقك بدلاً من مستخدم نهائي فردي. يطلب تطبيقك بيانات من Google APIs بالنيابة عن حساب الخدمة، لذلك لا يشارك المستخدمون بشكل مباشر. لمزيد من المعلومات عن طرق المصادقة، يُرجى الاطّلاع على مقالة طرق المصادقة في Google.

بدلاً من ذلك، يمكنك استخدام Geocoding API كجزء من تطبيق جوّال على Android أو iOS. للحصول على معلومات عامة حول استخدام OAuth مع Geocoding API، بما في ذلك معلومات حول إدارة رموز الوصول لبيئات النشر المختلفة، يُرجى الاطّلاع على استخدام OAuth 2.0 للوصول إلى Google APIs.

لمحة عن نطاقات OAuth

لاستخدام 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/maps-platform.geocode.location : يُستخدم فقط مع GeocodeLocation لعكس الترميز الجغرافي.
• https://www.googleapis.com/auth/maps-platform.geocode.place : يُستخدم فقط مع GeocodePlace للترميز الجغرافي للمكان.

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

مثال: تجربة طلبات REST API في بيئة التطوير المحلية

إذا أردت تجربة Geocoding API باستخدام رمز OAuth مميز، ولكن ليس لديك بيئة إعداد لإنشاء الرموز المميّزة، يمكنك استخدام الإجراء الوارد في هذا القسم لإجراء الطلب.

يوضّح هذا المثال كيفية استخدام رمز OAuth المميز الذي توفّره بيانات الاعتماد التلقائية للتطبيق (ADC) لإجراء الطلب. للحصول على معلومات حول استخدام بيانات الاعتماد التلقائية للتطبيق لطلب بيانات من Google APIs باستخدام مكتبات العملاء، يُرجى الاطّلاع على مقالة المصادقة باستخدام مكتبات العملاء.

ملاحظة: لا يُقصد استخدام الإجراء أدناه لإجراء طلب REST في بيئة التشغيل الفعلي. استخدِم هذا الإجراء لبيئة التطوير أو الاختبار فقط.

المتطلبات الأساسية

قبل أن تتمكّن من إجراء طلب REST باستخدام بيانات الاعتماد التلقائية للتطبيق، استخدِم Google Cloud CLI لتوفير بيانات الاعتماد لبيانات الاعتماد التلقائية للتطبيق:

1. ثبِّت gcloud CLI وابدأ إعداده.

2. شغِّل الأمر gcloud التالي على جهازك المحلي لإنشاء ملف بيانات الاعتماد:

   gcloud auth application-default login

3. تظهر شاشة تسجيل الدخول. بعد تسجيل الدخول، يتم تخزين بيانات الاعتماد في ملف بيانات الاعتماد المحلي الذي تستخدمه بيانات الاعتماد التلقائية للتطبيق.

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إعداد بيانات الاعتماد التلقائية للتطبيق لبيئة تطوير محلية.

إجراء طلب REST

في هذا المثال، يمكنك تمرير رأسَي طلب:

• مرِّر رمز OAuth المميز في رأس Authorization باستخدام الأمر التالي لإنشاء الرمز المميز:

  gcloud auth application-default print-access-token

  يحتوي الرمز المميز الذي يتم عرضه على نطاق https://www.googleapis.com/auth/cloud-platform.

• مرِّر رقم تعريف أو اسم مشروعك على Google Cloud الذي تم تفعيل الفوترة فيه في الـ X-Goog-User-Project رأس.

يُجري المثال التالي طلبًا إلى Geocoding API باستخدام رمز OAuth مميز.

1. عدِّل حقل PROJECT_ID لتمرير رقم تعريف مشروعك على Google Cloud.

   curl -X GET -H 'Content-Type: application/json' \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
   

2. انقر على رمز النسخ في نموذج الرمز البرمجي، , لنسخ أمر curl
3. الصِق الأمر في نافذة الوحدة الطرفية وشغِّله.

الردّ هو عنصر JSON:

تحديد المشاكل وحلّها

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