بهینه‌سازی استفاده از سهمیه هنگام زمین‌کدیابی

زمین‌کدیابی فرایند تبدیل نشانی‌ها («1600 Amphitheatre Parkway, Mountain View, CA») به مختصات جغرافیایی (37.423021, -122.083739) است که می‌توانید از آن برای قرار دادن نشانگرها یا موقعیت‌یابی نقشه استفاده کنید. میاناهای برنامه‌سازی کاربردی پلاتفرم Google Maps دو رویکرد برای زمین‌کدیابی ارائه می‌دهند:

  • زمین‌کدیابی سمت کارخواه، که در مرورگر اجرا می‌شود، معمولاً در پاسخ به کنش کاربر. ‫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 برای انجام درخواست زمین‌کدیابی سمت سرور در 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"
      ]
    }
  ]
}

برای مثال‌های بیشتر، نمای کلی Geocoding API v4 و راهنمای زمین‌کدیابی نشانی را ببینید.

ملاحظات سهمیه و هزینه

هزینه‌ها، سهمیه‌ها، و محدودیت‌های نرخ زمین‌کدیابی، راهبردهای شرح‌داده‌شده در این سند را هدایت می‌کنند.

هزینه

محدودیت‌های سهمیه در روز (QPD) برای درخواست‌های زمین‌کدیابی استفاده نمی‌شود. درعوض، هر درخواست زمین‌کدیابی، چه ازطریق مرورگر در سمت کارخواه باشد یا ازطریق سرویس وب Geocoding API در سمت سرور، با قیمت هر درخواست صورت‌حساب می‌شود. برای مدیریت هزینه استفاده، مدیریت کردن حدود استفاده و سهمیه‌ها را درنظر بگیرید.

حد نرخ

سرویس زمین‌کدیابی به ۳۰۰۰ پُرس‌وجو در دقیقه محدود شده است، که به‌عنوان مجموع پُرس‌وجوهای سمت کارخواه و سمت سرور محاسبه می‌شود.

هنگام اجرای درخواست‌های زمین‌کدیابی سمت کارخواه در فواصل زمانی دوره‌ای، مانند در یک برنامه تلفن همراه، اگر همه کاربران شما هم‌زمان درخواست ارسال کنند (مثلاً همه در یک ثانیه از هر دقیقه)، درخواست‌های شما ممکن است با خطا مواجه شوند. برای جلوگیری از این مشکل، یکی از موارد زیر را درنظر بگیرید:

  • فاصله‌های زمانی تصادفی به درخواست‌هایتان اضافه کنید (لرزش). مطمئن شوید درخواست‌ها در کل پایگاه کاربر شما تصادفی باشد.
  • اگر برای Android توسعه می‌دهید، از زنگ تکرارشونده غیردقیق استفاده کنید.
  • اگر برای Android توسعه می‌دهید، استراتژی مکان مناسبی را انتخاب کنید.

در حال ذخیره در حافظه نهان

برای اطلاعات بیشتر درباره ذخیره‌سازی در حافظه نهان، خط‌مشی‌های Geocoding API را ببینید.

معماری سمت سرور درمقابل سمت کارخواه در نسخه ۴

Geocoding API v4 (شامل SearchDestinations، GeocodeAddress، GeocodeLocation، و GeocodePlace) به‌عنوان میانای برنامه‌سازی کاربردی سروربه‌سرور طراحی شده است. فراخوانی نقاط پایانی نسخه ۴ از سرور زیرینه شما مزایای مهمی دارد:

  • هوش ورود محلی: روش SearchDestinations (POST /v4/geocode/destinations) منحصراً بااستفاده از درخواست‌های REST یا gRPC سمت سرور دردسترس است و ورودی‌های ساختمان، نقاط ناوبری قابل‌یابی، طرح‌های کلی ساختمان، و نشان‌های نزدیک را که در زمین‌کدیاب‌های مرورگر سمت کارخواه دردسترس نیستند برمی‌گرداند.
  • امنیت بهبودیافته میانای برنامه‌سازی کاربردی: تماس‌های سمت سرور از کلیدهای میانای برنامه‌سازی کاربردی و توکن‌های OAuth شما دربرابر افشا شدن در مرورگرهای کارخواه محافظت می‌کنند. امنیت میانای برنامه‌سازی کاربردی را ببینید.
  • پوشش‌های فیلد پاسخ: نقطه‌های پایانی v4 سمت سرور از پوشش‌های فیلد پشتیبانی می‌کنند و به شما امکان می‌دهند فقط فیلدهایی را درخواست کنید که برنامه‌تان برای به‌حداقل رساندن اندازه بار مفید و تأخیر نیاز دارد.

زمان استفاده از جستجوی مرورگر سمت کارخواه

برای برنامه‌های مرورگر تعاملی که به کلیدزنی‌های زنده پاسخ می‌دهند، ترکیب کردن تکمیل خودکار جا در سمت کارخواه (برای ابهام‌زدایی از ورودی کاربر و دریافت «شناسه جا») با فراخوانی پس‌بک به SearchDestinations یا GeocodePlace را برای بازیابی ایمن جزئیات یا مختصات محلی درنظر بگیرید.