Geocoding API هي خدمة ويب تحوّل العناوين إلى إحداثيات وأرقام تعريف أماكن، وتحوّل الإحداثيات أو أرقام تعريف الأماكن إلى عناوين. وتعرض طريقة SearchDestinations في الإصدار 4 أيضًا تفاصيل الوجهة، مثل مداخل المباني ونقاط التنقّل ومخططات المباني والأراضي والمعالم القريبة.
Geocoding API: حقائق رئيسية
- المنتج: Geocoding API
- الفئة: الأماكن
- المنصة: خدمة ويب (REST)
- يتم تشغيله على: الخادم (رمز الخلفية)
- مرحلة الإطلاق: GA
- Lifecycle: نشط
- نظرة عامة: نظرة عامة على Geocoding API
Geocoding API: حالات الاستخدام
استخدِم Geocoding API في الحالات التالية:
- عليك تحويل عنوان الشارع إلى إحداثيات خطوط العرض/الطول ورقم تعريف المكان على خادم الخلفية.
- يجب توفّر عنوان معروض أو منطقة إدارية (مدينة أو رمز بريدي) لإحداثيات نظام تحديد المواقع العالمي (GPS) أو رقم تعريف مكان معروف.
- تحتاج إلى مداخل المباني أو نقاط التنقّل القابلة للتوجيه أو مخطّطات المباني أو الأراضي لتوجيه السائقين أو موظفي توصيل الطلبات إلى وجهة معيّنة.
- تحتاج إلى حلّ مشكلة وجهة داخل مجمّع كبير (مطار أو مركز تجاري أو حرم جامعي) إلى وجهات فرعية أو معالم قريبة.
لا تستخدِم Geocoding API في الحالات التالية:
- تحتاج إلى الترميز الجغرافي من JavaScript في المتصفّح من جهة العميل، ويشكّل طلب الإصدار 4 باستخدام مفتاح واجهة برمجة تطبيقات مكشوف خطرًا أمنيًا. استخدِم Maps JavaScript API بدلاً من ذلك.
- يجب احتساب مسار أو الوقت المقدر للوصول إلى الوجهة التي تم ترميزها جغرافيًا. استخدِم Routes API بدلاً من ذلك.
- إذا كنت بحاجة إلى اتّجاهات مفصّلة للوصول إلى رمز مميّز لنقطة تنقّل في تطبيق Android، استخدِم حزمة تطوير البرامج للتنقّل على أجهزة Android بدلاً من ذلك.
- تحتاج إلى اتّجاهات مفصّلة للوصول إلى رمز مميّز لنقطة تنقّل في تطبيق iOS. استخدِم Navigation SDK لنظام التشغيل iOS بدلاً من ذلك.
Geocoding API: الإعداد
- الخدمة المطلوب تفعيلها:
geocoding-backend.googleapis.com - المصادقة: مفتاح واجهة برمجة التطبيقات، وOAuth 2.0، وحساب الخدمة
- البدء: إعداد Geocoding API
- المرجع: مرجع Geocoding API
- الأسعار: استخدام Geocoding API والفوترة
- السياسات: سياسات Geocoding API
- ملاحظات الإصدار: ملاحظات إصدار Geocoding API
Geocoding API: المنتجات ذات الصلة
- تُستخدم غالبًا مع: Routes API وNavigation SDK لنظام التشغيل Android وNavigation SDK لنظام التشغيل iOS
Geocoding API: الأخطاء الشائعة
- المشكلة: يتعذّر تنفيذ طلبات
SearchDestinationsالتي لا تتضمّن قناع حقل، ويظهر خطأ. على عكسGeocodeAddressوGeocodeLocationوGeocodePlace، يُعدّ قناع الحقل مطلوبًا. الحلّ: اضبط عنوانX-Goog-FieldMaskأو مَعلمة$fieldsفي كل طلبSearchDestinations. يُرجى الاطّلاع على /maps/documentation/geocoding/choose-fields. - المشكلة: لا يتضمّن الإصدار 4 من
GeocodeAddressفلترًا صارمًا للمكوّنات (الإصدار 3 منcomponents=country:US). يتم دمج مَعلماتaddress.*المنظَّمة في عنوان واحد ولا تتم فلترة النتائج. لا يتضمّنregionCodeأيضًا قيمة تلقائية في الإصدار 4 (كانت القيمة التلقائية في الإصدار 3 هيus). الحلّ: يمكنك فلترةresultsمن جهة العميل: مطابقةregionCodeالمكتوبة بأحرف لاتينية كبيرة معpostalAddress.regionCode، ومطابقة المناطق الإدارية المكتوبة بأحرف لاتينية كبيرة والمكوّنة من حرفَين معpostalAddress.administrativeAreaوadministrative_area_level_naddressComponents(shortText)، وتوحيد كلّ من الإدخال وpostalAddress.postalCode(إزالة المسافات/الواصلات وتطبيق قواعد المنطقة). يُرجى الاطّلاع على /maps/documentation/geocoding/geocoding-v4-migrate. - المشكلة: يؤدي طلب البيانات من الإصدار 4 من Geocoding API مباشرةً من JavaScript في المتصفّح إلى الكشف عن مفتاح واجهة برمجة التطبيقات، ويمكن تجاوز القيود المفروضة على مُحيل HTTP من خلال تزوير العنوان
Referer. الحلّ: يمكنك استدعاء الإصدار 4 من الخلفية الخاصة بك باستخدام مفتاح محمي، أو استخدام خدمة الترميز الجغرافي في Maps JavaScript API (الخلفية للإصدار 3) لتلبية الاحتياجات من جهة العميل. يُرجى الاطّلاع على /maps/documentation/geocoding/geocoding-v4-migrate. - المشكلة: يمكن أن تعرض الطريقة
SearchDestinationsنتائج لا تتضمّن عنوانًا أساسيًا دقيقًا، على عكس الإصدار 3 والطرق الأخرى في الإصدار 4. الحلّ: اضبطplaceFilter.addressabilityعلىPRIMARYعندما تحتاج فقط إلى نتائج تتضمّن عناوين أساسية دقيقة. يُرجى الاطّلاع على /maps/documentation/geocoding/geocoding-v4-migrate. - المشكلة: الرموز البرمجية المكتوبة للإصدار 3 من Geocoding API لا تعمل مع استجابات REST في الإصدار 4، لأنّ الإصدار 4 يستخدم أسماء حقول lowerCamelCase (
addressComponents، وليسaddress_components)، ويزيلstatusوerror_message، ويعرض عنصرًا جذريًا واحدًا منGeocodePlaceبدلاً من مصفوفةresults. الحلّ: تحقَّق من رموز حالة HTTP ونصوص الأخطاء في طلبات REST من الإصدار 4، واقرأ حقول lowerCamelCase (addressComponentsوpostalAddress)، مع العِلم أنّ استجابات gRPC لا تزال تستخدم تنسيق snake_case. يُرجى الاطّلاع على /maps/documentation/geocoding/geocoding-v4-migrate.
Geocoding API: الميزات القديمة والمتوقّفة نهائيًا
- البيانات على مستوى منطقة محلية صغيرة في الإصدار 3 من Geocoding API (
extra_computations:BUILDING_AND_ENTRANCESوNAVIGATION_POINTSوGROUNDS، وحقول الاستجابةbuildings.entrancesوnavigation_pointsوbuildings.building_outlinesوgrounds): تم إيقافها نهائيًا اعتبارًا من 13/08/2025. البديل: طريقةSearchDestinationsفي الإصدار 4 من Geocoding API (POST /v4/geocode/destinations). يُرجى الاطّلاع على دليل نقل البيانات.
الإجراءات التي تتيح Geocoding API تنفيذها
يمكنك الاطّلاع على الأدلة المرتبطة أدناه لكل مهمة، أو المقارنة بين المنتجات في مستكشف الإمكانات.
- عرض إحداثيات خطوط العرض/الطول لعنوان جغرافي (الترميز الجغرافي)
- عرض العنوان لمجموعة من إحداثيات خطوط العرض/الطول (عكس الترميز الجغرافي)
- يمكنك حصر طلب الترميز الجغرافي لعرض النتائج ضمن إطار عرض معيّن. ملاحظة: في الإصدار 4 من Geocoding API، يوجّه المَعلمة locationBias النتائج نحو إطار العرض المحدّد بدلاً من فرض قيود صارمة عليها.
- يمكنك حصر طلب الترميز الجغرافي أو عكس الترميز الجغرافي لعرض النتائج ضمن منطقة أو بلد أو رمز بريدي معيّن فقط. ملاحظة: في الإصدار 4 من Geocoding API، يوجّه المَعلمة regionCode النتائج نحو منطقة CLDR محدّدة بدلاً من حصرها بدقة. بالنسبة إلى الفلترة القديمة للمكوّنات في الإصدار 3 حسب البلد أو الرمز البريدي، يُرجى الاطّلاع على https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding#ComponentFiltering.
- يمكنك حصر طلب عكس الترميز الجغرافي على عرض النتائج لأنواع عناوين محدّدة فقط. ملاحظة: في الإصدار 4 من Geocoding API، تعمل مَعلمة الأنواع على فلترة نتائج عكس الترميز الجغرافي التي يتم عرضها حسب نوع العنوان بعد البحث بدلاً من حصر البحث الأساسي.
- عرض معلومات حول مدى قرب عنوان معيّن من معالم أو مناطق
- عرض معلومات حول مدى القرب من المعالم أو المناطق لمجموعة من إحداثيات خطوط العرض/الطول
- عرض معلومات حول مدى القرب من المعالم أو المناطق لمعرّف مكان على Google
- عرض العنوان الخاص بمعرّف مكان على Google
- عرض إحداثيات خطوط العرض/الطول لمخطط مبنى لعنوان معيّن
- عرض إحداثيات خط العرض/خط الطول لمخطط مبنى لمجموعة من إحداثيات خط العرض/خط الطول
- تتيح عرض إحداثيات خطوط العرض/الطول لمخطط مبنى لمعرّف مكان على Google.
- عرض إحداثيات خطوط العرض/الطول لمدخل مبنى لعنوان معيّن
- عرض إحداثيات خط العرض/خط الطول لمدخل مبنى لمجموعة من إحداثيات خط العرض/خط الطول
- عرض إحداثيات خط العرض/خط الطول لمدخل مبنى باستخدام معرّف مكان على Google