مرجع سريع حول Geocoding API

‫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 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_n addressComponents (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 تنفيذها

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