המונח המרה לקואורדינטות מתייחס בדרך כלל לתרגום של כתובת שאנשים יכולים לקרוא למיקום במפה. התהליך ההפוך, שבו ממירים מיקום במפה לכתובת שאנשים יכולים לקרוא, נקרא המרת קואורדינטות לכתובות (reverse geocoding).
בקשות להמרת קואורדינטות לכתובות (reverse geocoding)
פרמטרים נדרשים
latlng
– קואורדינטות של קווי רוחב ואורך שמציינות את המיקום שעבורו רוצים לקבל את הכתובת הקרובה ביותר שניתנת לקריאה על ידי בני אדם.key
– מפתח ה-API של האפליקציה. המפתח הזה מזהה את האפליקציה שלכם לצורכי ניהול מכסות. איך מקבלים מפתח
פרמטרים אופציונליים
אלה הפרמטרים האופציונליים שאפשר לכלול בבקשה לצורך גיאוקודינג הפוך:
language
– השפה שבה יוצגו התוצאות.- כאן אפשר לעיין ברשימת השפות הנתמכות. Google מעדכנת לעיתים קרובות את השפות הנתמכות, ולכן יכול להיות שהרשימה הזו לא תהיה מקיפה.
- אם לא מציינים את
language
, מקודד המיקום מנסה להשתמש בשפה המועדפת כפי שצוינה בכותרתAccept-Language
, או בשפה המקומית של הדומיין שממנו נשלחה הבקשה. - השירות למיפוי כתובות עושה כמיטב יכולתו כדי לספק כתובת רחוב שאפשר לקרוא גם למשתמש וגם לאנשים מקומיים. כדי להשיג את המטרה הזו, המערכת מחזירה כתובות רחוב בשפה המקומית, עם תעתיק שלהן לכתב שאפשר לקרוא על ידי המשתמש, אם יש צורך, בהתאם לשפה המועדפת. כל הכתובות האחרות יחזרו בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרת מהרכיב הראשון.
- אם שם לא זמין בשפה המועדפת, המערכת למיפוי גיאוגרפי משתמשת בהתאמה הקרובה ביותר.
region
– קוד האזור, שמצוין כערך בן שני תווים של דומיין ברמה עליונה עם קוד מדינה (ccTLD). הפרמטר יכול להשפיע גם על התוצאות בהתאם לדין החל.result_type
– מסנן של סוג כתובת אחד או יותר, שמופרד באמצעות צינור (|
). אם הפרמטר מכיל כמה סוגי כתובות, ה-API מחזיר את כל הכתובות שתואמות לאחד מהסוגים. הערה לגבי העיבוד: הפרמטרresult_type
לא מגביל את החיפוש לסוגים שצוינו של כתובות. במקום זאת, הערךresult_type
פועל כמסנן לאחר החיפוש: ה-API מאחזר את כל התוצאות שלlatlng
שצוין, ואז משמיד את התוצאות שלא תואמות לסוגים של הכתובות שצוינו. הערכים הבאים נתמכים:street_address
מציין כתובת רחוב מדויקת.route
מציין מסלול בעל שם (למשל 'US 101').intersection
מציין צומת ראשי, בדרך כלל של שני כבישים ראשיים.political
מציין ישות פוליטית. בדרך כלל, הסוג הזה מציין פוליגון של רשות אזרחית כלשהי.- הערך
country
מציין את הישות הפוליטית הלאומית, והוא בדרך כלל סוג הסדר הגבוה ביותר שמוחזר על ידי המקודד הגיאוגרפי. - הערך
administrative_area_level_1
מציין ישות אזרחית ברמה ראשונה מתחת לרמת המדינה. בארצות הברית, הרמות האלה הן המדינות. לא בכל המדינות יש את הרמות האלה של חלוקה מנהלית. ברוב המקרים, השמות המקוצרים של administrative_area_level_1 יהיו דומים מאוד לחלוקות משנה של ISO 3166-2 ולרשימות אחרות שפורסמו באופן נרחב. עם זאת, אין ערובה לכך כי תוצאות הגיאוקוד מבוססות על מגוון אותות ונתוני מיקום. administrative_area_level_2
מציין ישות אזרחית ברמה שנייה מתחת לרמת המדינה. בארצות הברית, הרמות האלה הן מחוזות. לא בכל המדינות יש את הרמות האלה של חלוקה מנהלית.administrative_area_level_3
מציין ישות אזרחית של סדר שלישי מתחת לרמת המדינה. הסוג הזה מציין חלוקה אזרחית משנית. לא בכל המדינות יש את הרמות האלה של חלוקה מנהלית.administrative_area_level_4
מציין ישות אזרחית ברמה הרביעית מתחת לרמת המדינה. הסוג הזה מציין חלוקה אזרחית משנית. לא בכל המדינות יש את הרמות האלה של חלוקה מנהלית.administrative_area_level_5
מציין ישות אזרחית ברמה החמישית מתחת לרמת המדינה. הסוג הזה מציין חלוקה אזרחית משנית. לא בכל המדינות יש את הרמות האלה של חלוקה מנהלית.administrative_area_level_6
מציין ישות אזרחית של סדר שישי מתחת לרמת המדינה. הסוג הזה מציין חלוקה אזרחית משנית. לא בכל המדינות יש את הרמות האלה של חלוקה מנהלית.administrative_area_level_7
מציין ישות אזרחית מסדר שביעי מתחת לרמת המדינה. הסוג הזה מציין חלוקה אזרחית משנית. לא בכל המדינות יש את הרמות האלה של חלוקה מנהלית.colloquial_area
מציין שם חלופי נפוץ של הישות.locality
מציין ישות פוליטית של עיר או עיירה מאוחדת.sublocality
מציין ישות אזרחית מדרגה ראשונה מתחת לאזור גיאוגרפי. למיקומים מסוימים עשוי להופיע אחד מהסוגים הנוספים:sublocality_level_1
עדsublocality_level_5
. כל רמת יישוב משנה היא ישות אזרחית. מספרים גדולים יותר מציינים אזור גיאוגרפי קטן יותר.neighborhood
מציין שכונה בעלת שם.premise
מציין מיקום בעל שם, בדרך כלל בניין או אוסף של בניינים עם שם משותף.subpremise
מציין ישות שניתן לשלוח אליה הודעות מתחת לרמת המקום, כמו דירה, יחידה או סוויטה.plus_code
מציין הפניה למיקום מקודד, שמבוססת על קו הרוחב וקו האורך. אפשר להשתמש ב-Plus Codes כתחליף לכתובות רחוב במקומות שבהם הן לא קיימות (במקומות שבהם אין מספרי בניינים או שמות רחובות). פרטים נוספים זמינים בכתובת https://plus.codes.postal_code
מציין מיקוד, כפי שהוא משמש לכתובת של דואר בתוך המדינה.natural_feature
מציין תכונה טבעית בולטת.airport
מציין נמל תעופה.park
מציין פארק בעל שם.point_of_interest
מציין נקודת עניין בעלת שם. בדרך כלל, 'נקודות העניין' האלה הן ישויות מקומיות בולטות שלא מתאימות בקלות לקטגוריה אחרת, כמו 'בניין האמפייר סטייט' או 'מגדל אייפל'.
location_type
– מסנן של סוג מיקום אחד או יותר, שמופרד באמצעות צינור (|
). אם הפרמטר מכיל כמה סוגי מיקום, ה-API מחזיר את כל הכתובות שתואמות לאחד מהסוגים. הערה לגבי העיבוד: הפרמטרlocation_type
לא מגביל את החיפוש לסוגים של המיקומים שצוינו. במקום זאת, השדהlocation_type
פועל כמסנן לאחר החיפוש: ה-API מאחזר את כל התוצאות שלlatlng
שצוין, ולאחר מכן משמיד את התוצאות שלא תואמות לסוגים של המיקומים שצוינו. יש תמיכה בערכים הבאים:- הפונקציה
"ROOFTOP"
מחזירה רק את הכתובות שלגביהן יש ל-Google מידע על המיקום מדויק עד לרמת הרחוב. - הפונקציה
"RANGE_INTERPOLATED"
מחזירה רק את הכתובות שמשקפות הערכה (בדרך כלל על דרך) שעבר אינטרפולציה בין שתי נקודות מדויקות (למשל צמתים). בדרך כלל, טווח משוער מציין שאין קואורדינטות גיאוגרפיות של גגות לכתובת רחוב. "GEOMETRIC_CENTER"
מחזירה רק את המרכזים הגיאומטריים של מיקום, כמו קו פוליגון (למשל, רחוב) או פוליגון (אזור)."APPROXIMATE"
מחזירה רק את הכתובות שמסווגות ככאלה שהן משוערות.
- הפונקציה
extra_computations
– אפשר להשתמש בפרמטר הזה כדי לציין את התכונות הנוספות הבאות בתגובה:ADDRESS_DESCRIPTORS
– פרטים נוספים זמינים במאמר תיאורי כתובות.BUILDING_AND_ENTRANCES
– פרטים נוספים זמינים במאמר כניסות וקווי מתאר של מבנים.
extra_computations
בבקשה לכל תכונה, לדוגמה:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
אם שני המסננים result_type
ו-location_type
נמצאים, ה-API מחזיר רק את התוצאות שתואמות גם לערך result_type
וגם לערך location_type
. אם אף אחד מערכי המסנן לא קביל, ה-API מחזיר את הערך ZERO_RESULTS
.
דוגמה להמרת קואורדינטות לכתובות (reverse geocoding)
השאילתה הבאה מכילה את הערך של קו הרוחב/קו האורך של מיקום בברוקלין:
https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY
השאילתה שלמעלה מחזירה את התוצאה הבאה:
{
"results" : [
{
"address_components" : [
{
"long_name" : "277",
"short_name" : "277",
"types" : [ "street_number" ]
},
{
"long_name" : "Bedford Avenue",
"short_name" : "Bedford Ave",
"types" : [ "route" ]
},
{
"long_name" : "Williamsburg",
"short_name" : "Williamsburg",
"types" : [ "neighborhood", "political" ]
},
{
"long_name" : "Brooklyn",
"short_name" : "Brooklyn",
"types" : [ "sublocality", "political" ]
},
{
"long_name" : "Kings",
"short_name" : "Kings",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "New York",
"short_name" : "NY",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
},
{
"long_name" : "11211",
"short_name" : "11211",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"geometry" : {
"location" : {
"lat" : 40.714232,
"lng" : -73.9612889
},
"location_type" : "ROOFTOP",
"viewport" : {
"northeast" : {
"lat" : 40.7155809802915,
"lng" : -73.9599399197085
},
"southwest" : {
"lat" : 40.7128830197085,
"lng" : -73.96263788029151
}
}
},
"place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
"types" : [ "street_address" ]
},
... Additional <code>results[]</code> ...
שימו לב שהמקודד הגיאוגרפית ההפוך החזיר יותר מתוצאה אחת. התוצאות של "formatted_address"
הן לא רק כתובות למשלוח דואר, אלא כל דרך לתיאור מיקום גיאוגרפי. לדוגמה, כשמבצעים גיאוקוד של נקודה בעיר תל אביב, הנקודה המתויגת יכולה להיות ככתובת רחוב, כעיר (תל אביב), כמדינה (ישראל) או כמדינה (ארצות הברית). כולם 'כתובות' למערכת המרת הכתובות לקואורדינטות. המערכת להמרת קואורדינטות לכתובות מחזירה את כל הסוגים האלה כתוצאות תקינות.
המרת הקואורדינטות לכתובות (reverse geocoding) מתאימה בין ישויות פוליטיות (מדינות, מחוזות, ערים ושכונות), כתובות רחוב ומספרי מיקוד.
הרשימה המלאה של ערכי formatted_address
שהוחזרו על ידי השאילתה הקודמת מוצגת בהמשך.
{
"plus_code" : {
"compound_code" : "P27Q+MCM New York, NY, USA",
"global_code" : "87G8P27Q+MCM"
},
"results" : [
{
"formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "street_address" ]
},
{
"formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "premise" ]
},
{
"formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "establishment", "point_of_interest" ]
},
{
"formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "route" ]
},
{
"formatted_address" : "P27Q+MC New York, NY, USA",
...
"types" : [ "plus_code" ]
},
{
"formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
...
"types" : [ "neighborhood", "political" ]
},
{
"formatted_address" : "Brooklyn, NY 11211, USA",
...
"types" : [ "postal_code" ]
},
{
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
...
"types" : [ "neighborhood", "political" ]
},
{
"formatted_address" : "Kings County, Brooklyn, NY, USA",
...
"types" : [ "administrative_area_level_2", "political" ]
},
{
"formatted_address" : "Brooklyn, NY, USA",
...
"types" : [ "political", "sublocality", "sublocality_level_1" ]
},
{
"formatted_address" : "New York, NY, USA",
...
"types" : [ "locality", "political" ]
},
{
"formatted_address" : "New York, USA",
...
"types" : [ "administrative_area_level_1", "political" ]
},
{
"formatted_address" : "United States",
...
"types" : [ "country", "political" ]
}
],
"status" : "OK"
}
ה-API הזה מחזיר סוגים שונים של כתובות, החל מכתובת הרחוב הספציפית ביותר ועד לישות פוליטיות פחות ספציפיות כמו שכונות, ערים, מחוזות ומדינות. בדרך כלל, הכתובת המדויקת יותר היא התוצאה הבולטת ביותר, כמו במקרה הזה. אם רוצים להתאים לכתובת מסוג ספציפי, אפשר לעיין בקטע הגבלת התוצאות לפי סוג בהמשך. לכן, המיקום של התוצאות ביחס זו לזו עשוי להשתנות.
המרת קואורדינטות לכתובות (reverse geocoding) עם סינון לפי סוג
בדוגמה הבאה, הכתובות שמוחזרות מסוננות כך שיכללו רק כתובות עם סוג מיקום ROOFTOP
וסוג כתובת street_address
.
https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY
הערה: המסננים האלה תקפים רק לצורך גיאוקודינג הפוך.
תשובות של המרת קואורדינטות לכתובות (reverse geocoding)
הפורמט של התגובה להמרת קואורדינטות לכתובות (reverse geocoding) זהה לפורמט של התגובה להמרת קואורדינטות. המרת קואורדינטות לכתובות (geocoding) של תשובות בהמשך מפורטים קודי הסטטוס האפשריים בתגובה של גיאוקודינג הפוך.
קודי סטטוס של המרת קואורדינטות לכתובות (reverse geocoding)
השדה "status"
באובייקט התשובה של המרת הקואורדינטות מכיל את סטטוס הבקשה, ויכול להכיל מידע על ניפוי באגים שיעזור לכם למצוא את הסיבה לכך שההמרה לא פועלת. השדה "status"
יכול להכיל את הערכים הבאים:
- הערך
"OK"
מציין שלא אירעו שגיאות ושהמערכת החזירה לפחות כתובת אחת. - הערך
"ZERO_RESULTS"
מציין שהגיאוקוד ההפוך בוצע בהצלחה, אבל לא החזיר תוצאות. מצב כזה יכול לקרות אם הועברו למקודד הגיאוגרפיהlatlng
במיקום מרוחק. "OVER_QUERY_LIMIT"
מציין שחרגתם מהמכסה."REQUEST_DENIED"
מציין שהבקשה נדחתה. יכול להיות שהסיבה לכך היא שהבקשה כוללת פרמטרresult_type
אוlocation_type
אבל לא כוללת מפתח API.- בדרך כלל, הערך
"INVALID_REQUEST"
מציין אחת מהאפשרויות הבאות:- השאילתה (
address
,components
אוlatlng
) חסרה. result_type
אוlocation_type
שצוינו לא תקינים.
- השאילתה (
- הערך
"UNKNOWN_ERROR"
מציין שלא ניתן היה לעבד את הבקשה עקב שגיאה בשרת. יכול להיות שהבקשה תצליח אם תנסה שוב.
המרת קואורדינטות לכתובות (reverse geocoding) של קודי OLC
השדה plus_code
בתשובה של השירות לצורך קביעת מיקום מכיל קוד OLC שמשויך לקו הרוחב ולקו האורך שהוזנו בשאילתה, והוא הקרוב ביותר למיקום בפועל.
בנוסף, מערך התוצאות של ה-JSON מכיל ברוב המקרים תוצאה מלאה של ניתוח מיקום עם סוג plus_code
וכתובת שמכילה קוד פלוס. המרחק בין קוד ה-Plus שעבר פענוח לנקודת הבקשה הוא פחות מ-10 מטרים.