الترميز الجغرافي للعناوين لاستخدامها في KML

مانو ماركس، فريق Google Geo
تاريخ الإنشاء: ديسمبر 2007
تاريخ التعديل: ديسمبر 2013

الهدف

هذا البرنامج التعليمي مخصّص للمطوّرين الذين لديهم خبرة في لغات البرمجة النصية ويريدون معرفة كيفية استخدام Google Geocoding API لترميز العناوين جغرافيًا ودمجها في ملف KML. على الرغم من أنّ عيّنات الرموز البرمجية معروضة بلغة Python، يمكن تكييفها بسهولة مع معظم لغات البرمجة الأخرى.

الترميز الجغرافي هو عملية تحويل عنوان إلى مجموعة من إحداثيات خطوط الطول والعرض، ما يتيح إمكانية تحديد العناوين على الخريطة. قد تحتاج إلى تحويل العناوين إلى رموز جغرافية وإدراجها مباشرةً في ملف KML. ويحدث ذلك عادةً، على سبيل المثال، عند إدخال البيانات في نموذج وإنشاء ملفات KML استجابةً للطلبات. يمكن تخزين ملفات KML هذه في قاعدة بيانات أو في نظام ملفات أو إرجاعها إلى NetworkLink يرتبط بملفك. يُرجى العِلم أنّه عند استخدام هذه الطريقة، عليك الالتزام ببنود الخدمة الخاصة بواجهة Geocoding API، إذ توجد بعض القيود على المدة التي يمكن فيها تخزين النتائج، بالإضافة إلى عدد العناصر التي يمكنك ترميزها جغرافيًا كل يوم.

يوضّح لك هذا البرنامج التعليمي كيفية استخدام Python لتحويل السلسلة "1600 Amphitheatre Pkwy, Mountain View, CA 94043" إلى ما يلي:

<?xml version='1.0' encoding='UTF-8'?> 
<kml xmlns='http://earth.google.com/kml/2.2'>
  <Document>
    <Placemark>
      <description>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</description>
      <Point>
        <coordinates>-122.081783,37.423111,0</coordinates>
      </Point>
    </Placemark>
  </Document>
</kml>

إنشاء مستند KML

‫KML هي لغة ترميز XML، لذا يمكننا استخدام دوال xml.dom.minidom المضمّنة في Python لإنشاء مستند KML. ‫minidom في Python هو تنفيذ DOM، ويكون DOM متاحًا في معظم لغات البرمجة، لذا يجب أن تكون عملية النقل إلى لغة برمجة أخرى سهلة. إليك الخطوات التي يمكنك اتّباعها:

1. أنشئ المستند باستخدام xml.dom.minidom.Document() في Python.
2. أنشئ عنصر <kml> الجذر باستخدام createElementNS.
3. أضِفها إلى المستند باستخدام appendChild.
4. أنشئ عنصر Document باستخدام createElement.
5. أضِفها إلى عنصر <kml> باستخدام appendChild.
6. لكل عنوان، أنشئ عنصر <Placemark> باستخدام createElement، وأضِفه إلى عنصر Document. بعد ذلك، أنشئ عنصر <description> وحدِّد له قيمة العنوان، ثم ألحِقه بالعنصر <Placemark>.
7. أنشئ عنصر <Point>، وأضِف عنصرًا ثانويًا <coordinates>، ثم أضِفه إلى العنصر <Placemark>.
8. أرسِل العنوان إلى أداة الترميز الجغرافي في Maps API، والتي سترسل استجابة بتنسيق JSON أو XML. استخدِم urllib.urlopen() لاسترداد الملف وقراءته في سلسلة.
9. حلّل الرد واستخرِج عناصر خط الطول وخط العرض.
10. أنشئ عقدة نصية في العنصر <coordinates> وعيِّن سلسلة خطوط الطول والعرض كقيمة لها.
11. اكتب مستند KML في ملف نصي.

نموذج لرمز Python البرمجي

يُرجى العِلم أنّ نموذج الرمز البرمجي أدناه يستخدم متغيّرًا وهميًا باسم mapsKey، وعليك استبدال هذا المفتاح بالمفتاح الخاص بك.

في ما يلي نموذج رمز لترميز الموقع الجغرافي باستخدام الإصدار 2.7 من Python وإخراج JSON:

import urllib
import xml.dom.minidom
import json 

def geocode(address, sensor=False):
 # This function queries the Google Maps API geocoder with an
 # address. It gets back a csv file, which it then parses and
 # returns a string with the longitude and latitude of the address.

 # This isn't an actual maps key, you'll have to get one yourself.
 # Sign up for one here: https://code.google.com/apis/console/
  mapsKey = 'abcdefgh'
  mapsUrl = 'https://maps.googleapis.com/maps/api/geocode/json?address='
     
 # This joins the parts of the URL together into one string.
  url = ''.join([mapsUrl,urllib.quote(address),'&sensor=',str(sensor).lower()])
#'&key=',mapsKey])
  jsonOutput = str(urllib.urlopen(url).read ()) # get the response 
  # fix the output so that the json.loads function will handle it correctly
  jsonOutput=jsonOutput.replace ("\\n", "")
  result = json.loads(jsonOutput) # converts jsonOutput into a dictionary 
  # check status is ok i.e. we have results (don't want to get exceptions)
  if result['status'] != "OK": 
    return ""
  coordinates=result['results'][0]['geometry']['location'] # extract the geometry 
  return str(coordinates['lat'])+','+str(coordinates['lng'])

def createKML(address, fileName):
 # This function creates an XML document and adds the necessary
 # KML elements.

  kmlDoc = xml.dom.minidom.Document()
  
  kmlElement = kmlDoc.createElementNS('http://earth.google.com/kml/2.2','kml')

  kmlElement = kmlDoc.appendChild(kmlElement)

  documentElement = kmlDoc.createElement('Document')
  documentElement = kmlElement.appendChild(documentElement)

  placemarkElement = kmlDoc.createElement('Placemark')
  
  descriptionElement = kmlDoc.createElement('description')
  descriptionText = kmlDoc.createTextNode(address)
  descriptionElement.appendChild(descriptionText)
  placemarkElement.appendChild(descriptionElement)
  pointElement = kmlDoc.createElement('Point')
  placemarkElement.appendChild(pointElement)
  coorElement = kmlDoc.createElement('coordinates')

  # This geocodes the address and adds it to a  element.
  coordinates = geocode(address)
  coorElement.appendChild(kmlDoc.createTextNode(coordinates))
  pointElement.appendChild(coorElement)

  documentElement.appendChild(placemarkElement)

  # This writes the KML Document to a file.
  kmlFile = open(fileName, 'w')
  kmlFile.write(kmlDoc.toprettyxml(' '))  
  kmlFile.close()

if __name__ == '__main__':
  createKML('1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA', 'google.kml')

أمور أخرى يجب أخذها في الاعتبار

تحديد توقيت طلبات الترميز الجغرافي

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

تغيير البلد الأساسي

تمت برمجة أداة الترميز الجغرافي لتحيز نتائجها استنادًا إلى النطاق المصدر. على سبيل المثال، سيؤدي إدخال "سيراكيوز" في مربّع البحث على maps.google.com إلى ترميز الموقع الجغرافي لمدينة "سيراكيوز، نيويورك"، بينما سيؤدي إدخال طلب البحث نفسه على maps.google.it (نطاق إيطاليا) إلى العثور على مدينة "سيراكوزا" في صقلية. يمكنك الحصول على النتائج نفسها من خلال إرسال طلب البحث هذا عبر الترميز الجغرافي HTTP إلى maps.google.it بدلاً من maps.google.com، ويمكنك إجراء ذلك من خلال تعديل المتغير mapsUrl في نموذج الرمز أعلاه. يُرجى الرجوع إلى مستندات Geocoding API للحصول على مزيد من المعلومات حول تحديد المنطقة.

ملاحظة: لا يمكنك إرسال طلب إلى خادم maps.google.* غير متوفّر، لذا تأكَّد من توفّر نطاق البلد قبل إعادة توجيه طلبات الترميز الجغرافي إليه. للاطّلاع على البلدان التي تتوفّر فيها رموز الترميز الجغرافي، يُرجى الاطّلاع على هذه المشاركة.

الخاتمة

باستخدام الرمز البرمجي أعلاه، يمكنك الآن تحويل عنوان إلى إحداثيات جغرافية باستخدام Python، وإنشاء ملف KML <Placemark> منه، وحفظه على القرص. إذا تبيّن لك أنّك بحاجة إلى ترميز جغرافي لعدد أكبر من العناوين يوميًا مما تسمح به الحدود، أو أنّ خدمة الترميز الجغرافي من Google لا تغطي المناطق التي تهمّك، ننصحك باستخدام خدمات ويب إضافية للترميز الجغرافي.

بعد أن تعرّفت على كيفية تحويل العناوين إلى رموز جغرافية، يمكنك الاطّلاع على المقالتَين حول استخدام KML في Google Mashup Editor واستخدام PHP وMySQL لإنشاء KML. إذا واجهت أي مشاكل أو كانت لديك أي أسئلة حول هذا البرنامج التعليمي، يُرجى نشرها في منتدى Stack Overflow.