גרסה 4 של Geocoding API מספקת שתי משפחות של יכולות עיקריות: חיפוש יעד למאפיינים עשירים של קהילה ממוקדת, והמרת כתובות בסיסית לקואורדינטות (המרת כתובת לקואורדינטות). לא בטוחים באיזו שיטה להשתמש? בחירת שיטה להמרת כתובות לקואורדינטות
- חיפוש יעדים (
SearchDestinations): מאחזר פרטי הגעה מפורטים ליעד – כולל כניסות לבניינים, נקודות ניווט שניתן לנתב אליהן, קווי מתאר של בניינים או שטחים, יעדי משנה וציוני דרך בקרבת מקום. - המרת כתובות לקואורדינטות (
GeocodeAddress): המרת כתובות לקואורדינטות של קו רוחב וקו אורך כדי להציב סמנים בסיסיים או למרכז מפה. - המרת קואורדינטות לכתובות (
GeocodeLocation): המרת קואורדינטות גיאוגרפיות לכתובת רחוב שקריאה לאנשים. - המרת כתובות של מקומות לקואורדינטות (
GeocodePlace): חיפוש הכתובת המעוצבת והקואורדינטות של מזהה מקום ידוע.
דוגמאות לבקשות ותשובות
הגישה ל-Geocoding API מתבצעת דרך ממשק HTTP. בהמשך מופיעות דוגמאות למדריכים למתחילים בנושאים חיפוש יעדים, המרה של כתובות לקואורדינטות (geocoding) והמרה של קואורדינטות לכתובות (reverse geocoding).
בקשה ותגובה לחיפוש יעדים (נתוני הגעה לקהילה ממוקדת)
בדוגמה הבאה נשלחת בקשת HTTP POST אל SearchDestinations עבור "1600 Amphitheatre Parkway, Mountain View, CA". שימו לב שצריך להוסיף ל-SearchDestinations כותרת X-Goog-FieldMask שמציינת את השדות שרוצים לקבל:
curl -X POST -d '{ "addressQuery": { "addressQuery": "1600 Amphitheatre Parkway, Mountain View, CA" } }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.formattedAddress,destinations.primary.location,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \ -H "X-Goog-Api-Key: YOUR_API_KEY" \ "https://geocode.googleapis.com/v4/geocode/destinations"
למטה מוצגת תגובה לדוגמה של SearchDestinations, שכוללת את פוליגון השטח של המבנה, הכניסות המועדפות, נקודות הניווט שניתן להגיע אליהן וציוני דרך בקרבת מקום:
{ "destinations": [ { "primary": { "displayName": { "text": "Googleplex", "languageCode": "en" }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "location": { "latitude": 37.4220656, "longitude": -122.0840897 }, "displayPolygon": { "type": "Polygon", "coordinates": [ [ [-122.084958, 37.422145], [-122.084112, 37.422610], [-122.083510, 37.421980], [-122.084958, 37.422145] ] ] } }, "entrances": [ { "location": { "latitude": 37.422189, "longitude": -122.084215 }, "tags": ["PREFERRED"] } ], "navigationPoints": [ { "navigationPointToken": "Eg...", "displayName": { "text": "Amphitheatre Pkwy Dropoff", "languageCode": "en" }, "location": { "latitude": 37.421912, "longitude": -122.084301 }, "travelModes": ["DRIVE"], "usages": ["DROPOFF", "PICKUP"] } ], "landmarks": [ { "place": { "displayName": { "text": "Charleston Park", "languageCode": "en" } }, "relationalDescription": { "text": "Adjacent to Charleston Park", "languageCode": "en" }, "straightLineDistanceMeters": 85.4 } ] } ] }
בקשה ותגובה להמרת כתובות לקואורדינטות (חיפוש קווי רוחב/אורך)
בדוגמה הבאה נשלחת בקשה לקבלת קו הרוחב וקו האורך של "1600 Amphitheatre Parkway, Mountain View, CA", ומצוין שהפלט צריך להיות בפורמט JSON.
curl -H "X-Goog-Api-Key: YOUR_API_KEY" \ "https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
כדי לבדוק את זה, אפשר להזין את כתובת ה-URL בדפדפן האינטרנט (חשוב להחליף את YOUR_API_KEY במפתח ה-API בפועל).
התשובה כוללת את קו הרוחב וקו האורך של הכתובת.
במדריך למפתחים מוסבר בפירוט איך ליצור כתובות URL לבקשות המרת כתובות לקואורדינטות, אילו פרמטרים זמינים ו איך להבין את התגובה.
בהמשך מוצגת דוגמה לתגובה של המרת כתובת לקואורדינטות, בפורמט JSON:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJ2Z2idB66j4ARI43TG-9RoCQ", "placeId": "ChIJ2Z2idB66j4ARI43TG-9RoCQ", "location": { "latitude": 37.4438238, "longitude": -122.0869895 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.4424748197085, "longitude": -122.0883384802915 }, "high": { "latitude": 37.445172780291493, "longitude": -122.08564051970852 } }, "formattedAddress": "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": "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" ] } ] }
בקשה ותגובה להמרת קואורדינטות לכתובות (חיפוש כתובת)
בדוגמה הבאה נשלחת בקשה לקבלת הכתובת שתואמת לקו הרוחב ולקו האורך שצוינו בברוקלין, ניו יורק, ארה"ב. הוא מציין שהפלט צריך להיות בפורמט JSON.
https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=YOUR_API_KEYכדי לבדוק את זה, מזינים את כתובת ה-URL בדפדפן האינטרנט (חשוב להחליף את הערך YOUR_API_KEY במפתח ה-API בפועל). התשובה כוללת כתובת קריאה לאנשים של מיקום קו הרוחב וקו האורך.
במדריך למפתחים מוסבר בפירוט איך ליצור כתובות URL לבקשות המרת קואורדינטות לכתובות, אילו פרמטרים זמינים ו איך להבין את התגובה.
בהמשך מוצגת דוגמה לתגובה של המרת קואורדינטות לכתובות, בפורמט JSON:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJHRNUiQK6j4ARJ__Hrbt6qsE", "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE", "location": { "latitude": 37.4225657, "longitude": -122.08465439999999 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.421214719708509, "longitude": -122.08603273029148 }, "high": { "latitude": 37.423912680291508, "longitude": -122.0833347697085 } }, "bounds": { "low": { "latitude": 37.4225178, "longitude": -122.08484599999998 }, "high": { "latitude": 37.422609600000008, "longitude": -122.0845215 } }, "formattedAddress": "Google Building 40, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94043", "administrativeArea": "CA", "locality": "Mountain View", "addressLines": [ "Google Building 40", "1600 Amphitheatre Pkwy" ] }, "addressComponents": [ { "longText": "Google Building 40", "shortText": "Google Building 40", "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" ] } ], "types": [ "street_address", "subpremise" ] }, ... Additional results truncated in this example[] ... }
אימות, מכסות, תמחור ומדיניות
אימות
כדי להשתמש ב-Geocoding API, קודם צריך להפעיל את ה-API ולקבל את פרטי הכניסה המתאימים לאימות. מידע נוסף זמין במאמר תחילת העבודה עם Google Maps Platform.
מכסות ותמחור
בדף שימוש וחיוב מפורטים המכסות והתמחור של Geocoding API.
מדיניות
השימוש ב-Geocoding API חייב להיות בהתאם למדיניות ה-API.