تحسين استخدام الحصة عند الترميز الجغرافي

الترميز الجغرافي هو عملية تحويل العناوين (مثل "1600 Amphitheatre Parkway, Mountain View, CA") إلى إحداثيات جغرافية (مثل 37.423021, ‎-122.083739)، والتي يمكنك استخدامها لوضع علامات أو تحديد موضع الخريطة. توفّر واجهات برمجة التطبيقات في "منصة خرائط Google" طريقتَين للترميز الجغرافي:

• الترميز الجغرافي من جهة العميل، الذي يتم تنفيذه في المتصفّح، عادةً استجابةً لإجراء المستخدم. توفّر Maps JavaScript API فئات تُجري الطلبات نيابةً عنك. يتم شرح هذا النهج في مستندات Maps JavaScript API.
• الترميز الجغرافي من جهة خادم HTTP، الذي يسمح للخادم بإرسال طلبات مباشرة إلى خوادم Google للحصول على الرموز الجغرافية ‫Geocoding API هي خدمة الويب التي توفّر هذه الوظيفة. عادةً ما يتم دمج هذه الخدمة مع رموز برمجية أخرى يتم تشغيلها من جهة الخادم. يتم شرح الترميز الجغرافي من جهة الخادم في مستندات Geocoding API.

أمثلة على الترميز الجغرافي من جهة العميل ومن جهة الخادم

في ما يلي نموذج من الترميز الجغرافي من جهة العميل الذي يأخذ عنوانًا ويرمّزه جغرافيًا وينقل مركز الخريطة إلى ذلك الموقع الجغرافي ويضيف علامة خريطة هناك:

geocoder = new google.maps.Geocoder();
geocoder.geocode({ 'address': address }, function(results, status) {
  if (status == google.maps.GeocoderStatus.OK) {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  }
});

لمزيد من الأمثلة، يُرجى الاطّلاع على مستندات Maps JavaScript API.

في ما يلي مثال على استخدام Python لإجراء طلب ترميز جغرافي من جهة الخادم في الإصدار 4 من Geocoding API:

import json
import urllib.request

address = "1600+Amphitheatre+Parkway,+Mountain+View,+CA"
key = "my-key-here"
url = f"https://geocode.googleapis.com/v4/geocode/address/{address}"
headers = {"X-Goog-Api-Key": key}

req = urllib.request.Request(url, headers=headers)
with urllib.request.urlopen(req) as response:
    result = json.loads(response.read().decode("utf-8"))

يؤدي ذلك إلى إنشاء عنصر JSON بالمحتوى التالي:

{
  "results": [
    {
      "place": "places/ChIJiSSC8QK6j4AR98Thup8mqTc",
      "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc",
      "location": {
        "latitude": 37.4224864,
        "longitude": -122.0855962
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4211700197085,
          "longitude": -122.08691558029149
        },
        "high": {
          "latitude": 37.4238679802915,
          "longitude": -122.08421761970851
        }
      },
      "bounds": {
        "low": {
          "latitude": 37.4221145,
          "longitude": -122.0860002
        },
        "high": {
          "latitude": 37.4228775,
          "longitude": -122.085133
        }
      },
      "formattedAddress": "Google Building 41, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "Google Building 41",
          "shortText": "Google Building 41",
          "types": [
            "premise"
          ],
          "languageCode": "en"
        },
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        },
        {
          "longText": "1351",
          "shortText": "1351",
          "types": [
            "postal_code_suffix"
          ]
        }
      ],
      "types": [
        "premise",
        "street_address"
      ]
    }
  ]
}

لمزيد من الأمثلة، يمكنك الاطّلاع على نظرة عامة على الإصدار 4 من Geocoding API ودليل الترميز الجغرافي للعنوان.

اعتبارات الحصة والتكلفة

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

التكلفة

لا يتم استخدام حدود الحصة اليومية (QPD) لطلبات الترميز الجغرافي. بدلاً من ذلك، يتم تحصيل رسوم لكل طلب ترميز جغرافي، سواء من جهة العميل من خلال المتصفّح أو من جهة الخادم من خلال خدمة الويب Geocoding API. لإدارة تكلفة الاستخدام، ننصحك بإدارة حدود الاستخدام والحصص.

ملاحظة مهمة: لاستخدام واجهات برمجة التطبيقات في "منصة خرائط Google"، عليك تفعيل الفوترة في كل مشروع من مشاريعك. في حال عدم إضافة حساب فوترة، ستنخفض جودة خرائطك أو ستعرض طلبات البيانات الأخرى من واجهة برمجة التطبيقات في "خرائط Google" رسالة خطأ.

الحدود القصوى لمعدّل الاستخدام

يتم تحديد معدّل خدمة الترميز الجغرافي بـ 3,000 طلب في الدقيقة، ويتم احتسابه كمجموع طلبات البحث من جهة العميل ومن جهة الخادم.

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

• أدخِل فواصل زمنية عشوائية إلى طلباتك (تأخير في الإرسال). تأكَّد من أنّ الطلبات عشوائية على مستوى قاعدة المستخدمين بالكامل.
• إذا كنت تطوّر تطبيقًا لنظام التشغيل Android، استخدِم منبّهًا متكررًا غير دقيق.
• في حال التطوير لنظام التشغيل Android، اختَر استراتيجية موقع جغرافي مناسبة.

التخزين المؤقت

يُرجى الاطّلاع على سياسات Geocoding API بشأن التخزين المؤقت.

بنية جهة الخادم مقابل بنية من جهة العميل في الإصدار 4

تم تصميم الإصدار 4 من Geocoding API (بما في ذلك SearchDestinations وGeocodeAddress وGeocodeLocation وGeocodePlace) كـ واجهة برمجة تطبيقات من خادم إلى خادم. يوفّر طلب نقاط نهاية الإصدار 4 من الخادم الخلفي مزايا مهمة:

• معلومات الوصول على مستوى منطقة محلية صغيرة: تتوفّر طريقة SearchDestinations (POST /v4/geocode/destinations) حصريًا باستخدام طلبات REST أو gRPC من جهة الخادم، وتعرض مداخل المباني ونقاط التنقّل القابلة للتوجيه ومخططات المباني والمعالم القريبة غير المتوفّرة في أدوات الترميز الجغرافي للمتصفّح من جهة العميل.
• أمان محسَّن لواجهة برمجة التطبيقات: تحمي الطلبات من جهة الخادم مفاتيح واجهة برمجة التطبيقات ورموز OAuth المميّزة من الكشف عنها في متصفّحات العملاء. يُرجى الاطّلاع على أمان واجهة برمجة التطبيقات.
• أقنعة حقول الاستجابة: تتيح نقاط النهاية من جهة الخادم في الإصدار 4 استخدام أقنعة الحقول، ما يتيح لك طلب الحقول التي يتطلّبها تطبيقك فقط لتقليل حجم الحمولة ووقت الاستجابة.

حالات استخدام البحث في المتصفّح من جهة العميل

بالنسبة إلى تطبيقات المتصفّح التفاعلية التي تستجيب لضغطات المفاتيح المباشرة، ننصحك بالجمع بين ميزة الإكمال التلقائي للأماكن من جهة العميل (لتوضيح إدخالات المستخدم والحصول على رقم تعريف المكان) مع طلب من الخلفية إلى SearchDestinations أو GeocodePlace لاسترداد التفاصيل أو الإحداثيات على مستوى منطقة محلية صغيرة بشكل آمن.