البدء

واجهة برمجة التطبيقات Geocoding API هي خدمة توفّر الترميز الجغرافي والترميز الجغرافي العكسي للعناوين.

الترميز الجغرافي هو عملية تحويل العناوين (مثل عنوان الشارع) إلى إحداثيات جغرافية (مثل خطوط الطول والعرض)، ويمكنك استخدامها لوضع العلامات على الخريطة أو تحديد موضع الخريطة.

الترميز الجغرافي العكسي هو عملية تحويل الإحداثيات الجغرافية إلى عنوان يمكن للمستخدمين قراءته.

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

نموذج لطلب وردّ

يمكنك الوصول إلى واجهة برمجة التطبيقات Geocoding API من خلال واجهة HTTP. وفي ما يلي أمثلة على طلبات الترميز الجغرافي وطلبات الترميز الجغرافي العكسي.

طلب واستجابة الترميز الجغرافي (البحث عن خطوط الطول/العرض)

يطلب المثال التالي خط العرض وخط الطول "1600 Amphitheatre Parkway, Mountain View, CA"، ويحدد أنّ الناتج يجب أن يكون بتنسيق JSON.

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

ويمكنك اختبار ذلك عن طريق إدخال عنوان URL في متصفح الويب (احرص على استبدال YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات الفعلي). يتضمن الرد خط العرض وخط الطول للعنوان.

راجِع دليل المطوِّر للحصول على مزيد من المعلومات حول إنشاء عناوين URL لطلبات الترميز الجغرافي والمَعلمات المتاحة و فهم الردّ.

فيما يلي نموذج لاستجابة الترميز الجغرافي بترميز JSON:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "1600",
               "short_name" : "1600",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Amphitheatre Parkway",
               "short_name" : "Amphitheatre Pkwy",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Mountain View",
               "short_name" : "Mountain View",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Clara County",
               "short_name" : "Santa Clara County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "California",
               "short_name" : "CA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "94043",
               "short_name" : "94043",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
         "geometry" : {
            "location" : {
               "lat" : 37.4267861,
               "lng" : -122.0806032
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 37.4281350802915,
                  "lng" : -122.0792542197085
               },
               "southwest" : {
                  "lat" : 37.4254371197085,
                  "lng" : -122.0819521802915
               }
            }
         },
         "place_id" : "ChIJtYuu0V25j4ARwu5e4wwRYgE",
         "plus_code" : {
            "compound_code" : "CWC8+R3 Mountain View, California, United States",
            "global_code" : "849VCWC8+R3"
         },
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

طلب واستجابة الترميز الجغرافي العكسي (البحث عن العنوان)

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

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

يمكنك اختبار ذلك عن طريق إدخال عنوان URL في متصفح الويب (احرص على استبدال "YOUR_API_KEY" بمفتاح واجهة برمجة التطبيقات الفعلي). يتضمن الردّ عنوانًا يمكن للإنسان قراءته لخط الطول وخط العرض.

راجِع دليل المطوّر للحصول على مزيد من المعلومات حول إنشاء عناوين URL لطلبات الترميز الجغرافي العكسي والمَعلمات المتاحة و فهم الردّ.

وفي ما يلي نموذج لاستجابة ترميز جغرافي عكسي بتنسيق JSON:

{
   "plus_code" : {
      "compound_code" : "P27Q+MC New York, NY, USA",
      "global_code" : "87G8P27Q+MC"
   },
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "279",
               "short_name" : "279",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "political", "sublocality", "sublocality_level_1" ]
            },
            {
               "long_name" : "Kings County",
               "short_name" : "Kings County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.7142484,
               "lng" : -73.9614103
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.71559738029149,
                  "lng" : -73.9600613197085
               },
               "southwest" : {
                  "lat" : 40.71289941970849,
                  "lng" : -73.96275928029151
               }
            }
         },
         "place_id" : "ChIJT2x8Q2BZwokRpBu2jUzX3dE",
         "plus_code" : {
            "compound_code" : "P27Q+MC Brooklyn, New York, United States",
            "global_code" : "87G8P27Q+MC"
         },
         "types" : [
            "bakery",
            "cafe",
            "establishment",
            "food",
            "point_of_interest",
            "store"
         ]
      },

   ... Additional results truncated in this example[] ...

   ],
   "status" : "OK"
}

ابدأ الترميز باستخدام مكتبات العملاء

تسهّل مكتبات العملاء عملية التطوير باستخدام واجهات برمجة التطبيقات لخدمة الويب في "خرائط Google"، وذلك من خلال توفير عمليات تنفيذ بسيطة ومبتكرة للمهام الشائعة، مثل المصادقة وتقييد الطلبات وإعادة المحاولة تلقائيًا. تتوفر واجهة برمجة التطبيقات Geocoding API في برنامج عميل Java وبرنامج Python وGo Client وعميل Node.js لخدمات خرائط Google.

المصادقة والحصص والأسعار والسياسات

المصادقة

لاستخدام واجهة برمجة التطبيقات Geocoding API، عليك أولاً تفعيل واجهة برمجة التطبيقات والحصول على بيانات اعتماد المصادقة المناسبة. لمزيد من المعلومات، اطّلِع على بدء استخدام "منصة خرائط Google".

الحصص والأسعار

يمكنك مراجعة صفحة الاستخدام والفوترة للحصول على تفاصيل حول الحصص والأسعار المحدّدة لواجهة برمجة تطبيقات الترميز الجغرافي.

السياسات

ويجب أن يتوافق استخدام واجهة برمجة التطبيقات Geocoding مع سياسات واجهة برمجة التطبيقات.

مزيد من المعلومات

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

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