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