הגדרת Geocoding API

מפתחים באזור הכלכלי האירופי (EEA)

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

במאמר הזה מוסבר איך להתחיל להשתמש ב-Geocoding API.

1. חשבון וחיוב מוודאים שאתם עומדים בדרישות הסף.

2. מפעילים את ה-API מפעילים את ה-API בפרויקט בענן ב-Google Cloud.

3. שליחת הבקשה הראשונה מגדירים מפתח API או OAuth כדי לשלוח בקשת API מאומתת.

נקודה חשובה: מדריך ההגדרה הזה כולל את ההליך של הגדרת מפתח API ושל יצירת טוקן OAuth. בוחרים את ההליך שרלוונטי לסביבת הפריסה.

המוצרים של Google Maps Platform מוגנים מפני שימוש לא מורשה, כי קריאות ל-API צריכות לכלול או מפתח API או אסימון OAuth.

מפתח API טוקן OAuth

יצירת טוקן OAuth

‫Geocoding API תומך בשימוש ב-OAuth 2.0 לאימות. ‫Google תומכת בתרחישים נפוצים של OAuth 2.0, כמו אלה של שרת אינטרנט.

במאמר הזה מוסבר איך להעביר אסימון OAuth לקריאה ל-Geocoding API בסביבת הפיתוח. הוראות לשימוש ב-OAuth בסביבת ייצור זמינות במאמר בנושא שיטות אימות ב-Google.

הערה:

אמנם אפשר להשתמש ישירות בממשקי Google Maps APIs על ידי שליחת בקשות API לשרת, אבל ספריות לקוח מפשטות את התהליך ומפחיתות באופן משמעותי את כמות הקוד שתצטרכו לכתוב. מפות Google מספקת ספריות לקוח לשפות תכנות רבות, כולל Go,‏ Java,‏ Node.js ו-Python.

במאמר ספריות לקוח של Geocoding API אפשר למצוא תיעוד ודוגמאות.

מידע על OAuth

יש הרבה דרכים ליצור ולנהל טוקנים של גישה באמצעות OAuth, בהתאם לסביבת הפריסה שלכם.

לדוגמה, מערכת Google OAuth 2.0 תומכת באינטראקציות בין שרתים, כמו אלה שבין האפליקציה שלכם לבין שירות של Google. במקרה הזה צריך חשבון שירות, שהוא חשבון ששייך לאפליקציה ולא למשתמש קצה ספציפי. האפליקציה שולחת קריאות ל-Google APIs בשם חשבון השירות, כך שהמשתמשים לא מעורבים באופן ישיר. מידע נוסף על שיטות אימות זמין במאמר בנושא שיטות אימות ב-Google.

אפשרות אחרת היא להשתמש ב-Geocoding API כחלק מאפליקציה לנייד ל-Android או ל-iOS. למידע כללי על שימוש ב-OAuth עם Geocoding API, כולל מידע על ניהול אסימוני גישה לסביבות פריסה שונות, אפשר לעיין במאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.

מידע על היקפי הרשאות OAuth

כדי להשתמש ב-OAuth עם Geocoding API, צריך להקצות לטוקן OAuth את ההיקף הנכון. ‫Geocoding API תומך בהיקפים הבאים:

• https://www.googleapis.com/auth/maps-platform.geocode ‫— לשימוש בכל ה-methods של Geocoding API.
• https://www.googleapis.com/auth/maps-platform.geocode.address ‫— אפשר להשתמש רק ב-GeocodeAddress לגיאו-קידוד קדימה.
• https://www.googleapis.com/auth/maps-platform.geocode.location ‫— אפשר להשתמש רק ב-GeocodeLocation להמרת קואורדינטות לכתובות (reverse geocoding).
• https://www.googleapis.com/auth/maps-platform.geocode.place ‫— אפשר להשתמש רק עם GeocodePlace לגיאו-קידוד של מקומות.

בנוסף, אפשר להשתמש בהיקף הכללי https://www.googleapis.com/auth/cloud-platform לכל ה-methods של Geocoding API. ההיקף הזה שימושי במהלך הפיתוח כי הוא היקף ברירת המחדל שמשמש ליצירת טוקנים באמצעות gcloud.

דוגמה: התנסות בקריאות ל-API בארכיטקטורת REST בסביבת הפיתוח המקומית

אם אתם רוצים לנסות את Geocoding API באמצעות טוקן OAuth, אבל אין לכם סביבה להגדרת יצירת טוקנים, אתם יכולים להשתמש בתהליך שמתואר בקטע הזה כדי לבצע את הקריאה.

בדוגמה הזו אנחנו מסבירים איך להשתמש באסימון OAuth שסופק על ידי Application Default Credentials ‏ (ADC) כדי לבצע את הקריאה. במאמר אימות באמצעות ספריות לקוח תוכלו ללמוד איך משתמשים ב-ADC כדי לקרוא ל-Google APIs באמצעות ספריות לקוח.

הערה: התהליך שמתואר בהמשך לביצוע קריאת REST לא מיועד לשימוש בסביבת ייצור. התהליך הזה מיועד לשימוש רק בסביבת פיתוח או בדיקה.

דרישות מוקדמות

כדי שתוכלו לשלוח בקשת REST באמצעות ADC, אתם צריכים קודם לספק ל-ADC את פרטי הכניסה באמצעות Google Cloud CLI:

1. מתקינים ומפעילים את ה-CLI של gcloud.

2. מריצים את הפקודה gcloud הבאה במחשב המקומי כדי ליצור את קובץ פרטי הכניסה:

   gcloud auth application-default login

3. מסך התחברות יוצג לפניכם. אחרי שמתחברים, פרטי הכניסה נשמרים בקובץ פרטי הכניסה המקומי שמשמש את ADC.

מידע נוסף זמין במאמר הגדרת ADC לסביבת פיתוח מקומית.

שליחת בקשת REST

בדוגמה הזו, מעבירים שתי כותרות בקשה:

• מעבירים את אסימון ה-OAuth בכותרת Authorization באמצעות הפקודה הבאה ליצירת האסימון:

  gcloud auth application-default print-access-token

  הטוקן שמוחזר כולל את ההיקף https://www.googleapis.com/auth/cloud-platform.

• מעבירים את המזהה או השם של פרויקט בענן ב-Google שבו מופעל החיוב בכותרת X-Goog-User-Project.

בדוגמה הבאה מוצגת קריאה אל Geocoding API באמצעות טוקן OAuth.

1. עורכים את השדה PROJECT_ID כדי להעביר את המזהה של פרויקט בענן ב-Google Cloud.

   curl -X GET -H 'Content-Type: application/json' \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
   

2. לוחצים על סמל ההעתקה בדוגמת הקוד, , כדי להעתיק את הפקודה curl.
3. מדביקים את הפקודה בחלון טרמינל ומריצים אותה.

התגובה היא אובייקט JSON:

פתרון בעיות

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