המונח קידוד גיאוגרפי מתייחס בדרך כלל לתרגום כתובת שאנשים יכולים לקרוא למיקום במפה. תהליך ההפוך, תרגום מיקום במפה לכתובת שאנשים יכולים לקרוא, נקרא קידוד גיאוגרפי הפוך.
היפוך בקשות לקידוד גיאוגרפי
פרמטרים נדרשים
latlng
— קואורדינטות של קווי אורך ורוחב שמציינות את המיקום שעבורו ברצונכם למצוא את הכתובת הקרובה ביותר, שניתנת לקריאה על ידי אנשים.key
- מפתח ה-API של האפליקציה. המפתח הזה מזהה את האפליקציה שלכם לצורך ניהול המכסות. כך מקבלים מפתח
פרמטרים אופציונליים
אלה הפרמטרים האופציונליים שאפשר לכלול בבקשת קידוד גיאוגרפי הפוך:
language
— השפה שבה יוחזרו תוצאות.- כאן אפשר לעיין ברשימת השפות הנתמכות. Google מעדכנת לעיתים קרובות את השפות הנתמכות, ולכן ייתכן שהרשימה הזו חלקית.
- אם לא תספקו את הערך
language
, הקוד לקואורדינטות (geocoding) ינסה להשתמש בשפה המועדפת שצוינה בכותרתAccept-Language
, או בשפת האם של הדומיין שממנו הבקשה נשלחת. - המקודד הגיאוגרפי עושה כמיטב יכולתו כדי לספק כתובת רחוב שתהיה קריאה גם למשתמש וגם למקומיים. כדי להשיג את המטרה הזו, הפונקציה מחזירה כתובות רחובות בשפה המקומית, שמתועתקת לסקריפט שהמשתמש יכול לקרוא במקרה הצורך, תוך תוך שימוש בשפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, הנבחרת מהרכיב הראשון.
- אם שם אינו זמין בשפה המועדפת, המקודד הגיאוגרפי ישתמש בהתאמה הקרובה ביותר.
region
- קוד האזור, שמצוין כ-ccTLD ("דומיין ברמה העליונה") בן שני תווים. הפרמטר יכול גם להשפיע על התוצאות בהתאם לדין החל.result_type
- מסנן של סוג כתובת אחד או יותר, שמופרד באמצעות קו אנכי (|
). אם הפרמטר מכיל כמה סוגי כתובות, ה-API מחזיר את כל הכתובות שתואמות לאחד מהסוגים. הערה לגבי העיבוד: הפרמטרresult_type
לא restrict את החיפוש לסוגי הכתובות שצוינו. במקום זאת,result_type
משמש כמסנן לאחר חיפוש: ה-API מאחזר את כל התוצאות עבורlatlng
שצוין, ולאחר מכן מוחק את התוצאות שלא תואמות לסוגי הכתובות שצוינו. הערכים הבאים נתמכים:street_address
מציין כתובת רחוב מדויקת.route
מציין נתיב בעל שם (למשל, "US 101").intersection
מציין צומת ראשי, בדרך כלל עם שתי דרכים ראשיות.political
מציין ישות פוליטית. בדרך כלל, הסוג הזה מציין פוליגון של מנהל אזרחי כלשהו.country
מציין את הישות הפוליטית הלאומית, ובדרך כלל הוא סוג הסדר הגבוה ביותר שמוחזר על ידי המקודד הגיאוגרפי.administrative_area_level_1
מציין ישות אזרחית מסדר ראשון מתחת לרמת המדינה. בארצות הברית, הרמות המנהליות האלה הן מדינות. לא בכל המדינות מוצגות רמות ניהול אלה. ברוב המקרים, השמות המקוצרים של admin_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
מציין הפניה מקודדת למיקום, שנגזרת מקווי אורך ורוחב. אפשר להשתמש ב-OLC כתחליף לכתובות במקומות שבהם הן לא קיימות (שבהם מבנים לא ממוספרים או לא נקובים שמות של רחובות). פרטים נוספים זמינים בכתובת https://plus.codes.postal_code
מציין מיקוד המשמש לטיפול בדואר בתוך המדינה.natural_feature
מציין תכונה טבעית בולטת.airport
מציין נמל תעופה.park
מציין פארק בעל שם.point_of_interest
מציין נקודת עניין בעלת שם. בדרך כלל, נקודות העניין האלה הן ישויות מקומיות בולטות שלא מתאימות בקלות לקטגוריה אחרת, כמו 'בניין אמפייר סטייט' או 'מגדל אייפל'.
location_type
- מסנן של סוג מיקום אחד או יותר, שמופרד באמצעות קו אנכי (|
). אם הפרמטר מכיל מספר סוגי מיקומים, ה-API מחזיר את כל הכתובות שתואמות לאחד מהסוגים. הערה לגבי העיבוד: הפרמטרlocation_type
לא restrict את החיפוש לסוגי המיקומים שצוינו. במקום זאת,location_type
משמש כמסנן לאחר חיפוש: ה-API מאחזר את כל התוצאות עבורlatlng
שצוינו, ולאחר מכן מוחק את התוצאות שלא תואמות לסוגי המיקומים שצוינו. המערכת תומכת בערכים הבאים:"ROOFTOP"
מחזירה רק את הכתובות שעבורן ל-Google יש פרטי מיקום מדויקים עד לרמת הדיוק של כתובת הרחוב.- הפונקציה
"RANGE_INTERPOLATED"
מחזירה רק את הכתובות שמשקפות קירוב (בדרך כלל על הכביש) שעוברות אינטרפולציה בין שתי נקודות מדויקות (כגון צמתים). טווח אינטרפולציה מציין בדרך כלל שאין קודים גיאוגרפיים על הגגות עבור כתובת רחוב. - הפונקציה
"GEOMETRIC_CENTER"
מחזירה רק מרכזים גיאומטריים של מיקום, כמו קו פוליגוני (לדוגמה, רחוב) או פוליגון (אזור). - הפונקציה
"APPROXIMATE"
מחזירה רק את הכתובות שמופיעות כמשוער.
אם גם המסננים result_type
וגם המסננים location_type
קיימים, ה-API מחזיר רק את התוצאות שתואמות גם לערך result_type
וגם לערך location_type
. אם אף אחד מהערכים של המסנן לא קביל, ה-API מחזיר את הערך ZERO_RESULTS
.
דוגמה לקידוד גיאוגרפי הפוך
השאילתה הבאה מכילה את ערך קו הרוחב/קו האורך של מיקום בברוקלין:
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"
הן לא רק כתובות למשלוח דואר, אלא כל דרך לתת שם גיאוגרפי למיקום. לדוגמה, כשמקודדים גיאוגרפית נקודה בעיר שיקגו, אפשר לסמן אותה בתור כתובת רחוב, בתור העיר (שיקגו), כמדינה שלה או כמדינה (ארה"ב). כולן הן 'כתובות' של הכלי לקואורדינטות. המקודד ההפוך מחזיר כל אחד מהסוגים האלה כתוצאות חוקיות.
הממיר הגאוגרפי ההפוך תואם לישויות פוליטיות (מדינות, מחוזות, ערים ושכונות), רחובות ומספרי מיקוד.
הרשימה המלאה של ערכי 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 הזה מחזיר סוגים שונים של כתובות, החל בכתובת הרחוב הספציפית ביותר ועד לישויות פוליטיות פחות ספציפיות כמו שכונות, ערים, מחוזות ומדינות. בדרך כלל, הכתובת המדויקת יותר היא התוצאה הבולטת ביותר, שכן במקרה זה. אם ברצונך להתאים סוג כתובת ספציפי, עיינו למטה בקטע הגבלת תוצאות לפי סוג. לכן, מיקום התוצאות יחסית עשוי להשתנות.
קידוד גיאוגרפי הפוך מסונן לפי סוג
הדוגמה הבאה מסננת את הכתובות שהוחזרו כך שיכללו רק כתובות עם סוג מיקום 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
הערה: המסננים האלה תקפים רק לקידוד גיאוגרפי הפוך.
תגובות הפוך לגבי קידוד גיאוגרפי
הפורמט של התגובה לקידוד גיאוגרפי הפוך זהה לזה של התגובה לקידוד גיאוגרפי. ראו תגובות לקידוד גיאוגרפי. בהמשך מופיעים קודי המצב האפשריים בתגובה באמצעות קידוד גיאוגרפי הפוך.
היפוך קודי סטטוס של קידוד גיאוגרפי
השדה "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"
מציין שלא ניתן היה לעבד את הבקשה עקב שגיאה בחיבור לשרת. ייתכן שהבקשה תצליח אם תנסה שוב.
קידוד גיאוגרפי הפוך בתוספת קודים
השדה plus_code
בתגובת הקידוד הגיאוגרפי מכיל סימן 'פלוס' המתאים בצורה הטובה ביותר לקווי האורך והרוחב של השאילתות.
בנוסף, מערך התוצאות של JSON מכיל ברוב המקרים תוצאת קידוד גיאוגרפי מלאה עם סוג plus_code
וכתובת שמכילה קוד פלוס. המרחק בין קוד הפלוס המפוענח לבין נקודת הבקשה יכול להיות פחות מ-10 מטרים.