אופטימיזציה של השימוש במכסה בעת קידוד גיאוגרפי

המרת כתובות לקואורדינטות (geocoding) היא תהליך של המרת כתובות ("1600 Amphitheatre Parkway, Mountain View, CA") לקואורדינטות גיאוגרפיות (37.423021, ‎-122.083739), שבהן אפשר להשתמש כדי להציב סמנים או למקם את המפה. בממשקי ה-API של Google Maps Platform יש שתי גישות להמרת כתובות לקואורדינטות:

• המרת כתובות לקואורדינטות בצד הלקוח, שמתבצעת בדפדפן, בדרך כלל בתגובה לפעולת משתמש. ב-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 v4:

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, מחויבת במחיר לכל בקשה. כדי לנהל את עלות השימוש, כדאי לנהל את מגבלות השימוש והמכסות.

חשוב: כדי להשתמש בממשקי ה-API של Google Maps Platform, צריך להפעיל את החיוב בכל אחד מהפרויקטים. אם לא תוסיפו חשבון לחיוב, מפות Google שלכם יופיעו באיכות נמוכה יותר, או שבקשות API אחרות ל-Maps API יחזירו שגיאה.

מגבלות קצב

השירות להמרת כתובות לקואורדינטות מוגבל ל-3,000 שאילתות לדקה (QPM), שמחושבות כסכום השאילתות בצד הלקוח ובצד השרת.

כשמריצים בקשות להמרת כתובות לקואורדינטות בצד הלקוח במרווחי זמן קבועים, למשל באפליקציה לנייד, יכול להיות שהבקשות יחזירו שגיאות אם כל המשתמשים שולחים בקשות בו-זמנית (לדוגמה, כולם באותה שנייה בכל דקה). כדי למנוע את זה, אפשר:

• הוסיפו מרווחים אקראיים לבקשות (ריצוד). חשוב לוודא שהבקשות נשלחות באופן אקראי לכל בסיס המשתמשים.
• אם אתם מפתחים ל-Android, השתמשו בהתראה חוזרת לא מדויקת.
• אם אתם מפתחים ל-Android, בחרו אסטרטגיית מיקום מתאימה.

שמירה במטמון

מידע נוסף על שמירה במטמון זמין במאמר המדיניות של Geocoding API.

ארכיטקטורה בצד השרת לעומת ארכיטקטורה בצד הלקוח ב-v4

‫Geocoding API v4 (כולל SearchDestinations,‏ GeocodeAddress,‏ GeocodeLocation ו-GeocodePlace) הוא API שפועל משרת לשרת. הפעלת נקודות קצה (endpoint) של גרסה 4 משרת בק-אנד שלכם מספקת יתרונות חשובים:

• מידע חכם על הגעה למיקום ספציפי: השיטה SearchDestinations (POST /v4/geocode/destinations) זמינה רק באמצעות בקשות REST או gRPC בצד השרת, ומחזירה כניסות לבניינים, נקודות ניווט שניתן לנתב אליהן, קווי מתאר של בניינים וציוני דרך בקרבת מקום שלא זמינים בכלים להמרת כתובות לקואורדינטות בדפדפן בצד הלקוח.
• אבטחת API משופרת: קריאות בצד השרת מגינות על מפתחות ה-API ועל אסימוני ה-OAuth מפני חשיפה בדפדפנים של הלקוחות. אבטחת API
• מסכות שדות בתגובה: נקודות קצה (endpoint) בצד השרת בגרסה 4 תומכות במסכות שדות, שמאפשרות לבקש רק את השדות שהאפליקציה צריכה כדי לצמצם את גודל המטען הייעודי (payload) ואת זמן האחזור.

מתי כדאי להשתמש בחיפוש בדפדפן בצד הלקוח

באפליקציות אינטראקטיביות בדפדפן שמגיבות להקשות מקשים בזמן אמת, כדאי לשלב את ההשלמה האוטומטית למקומות בצד הלקוח (כדי להבהיר את קלט המשתמש ולקבל מזהה מקום) עם קריאה לקצה העורפי אל SearchDestinations או אל GeocodePlace כדי לאחזר פרטים או קואורדינטות של קהילה ממוקדת באופן מאובטח.