שנתחיל?

מבוא

ה-API סטטי של מפות Google מחזיר תמונה (GIF, PNG או JPEG) בתגובה לבקשת HTTP דרך כתובת URL. לכל בקשה אפשר לציין את המיקום של המפה, את גודל התמונה, את רמת הזום, את סוג המפה ואת המיקום של סמנים אופציונליים במיקומים במפה. ניתן גם לתייג את הסמנים באמצעות תווים אלפאנומריים.

תמונה של ה-API הסטטי של מפות Google מוטמעת במאפיין src של התג <img>, או במאפיין המקביל שלו בשפות תכנות אחרות.

במסמך הזה מתוארים הפורמט הנדרש של כתובות URL של ה-API הסטטי של מפות Google והפרמטרים הזמינים. הוא גם כולל כמה טיפים וטריקים להגדרת כתובות אתרים.

לפני שמתחילים

מסמך זה מיועד למפתחי אתרים וניידים שרוצים לכלול תמונות של Maps Static API בדף אינטרנט או באפליקציה לנייד. מבוא לשימוש ב-API ובחומרי העזר לפרמטרים הזמינים.

לפני שמתחילים לפתח את Maps Static API, כדאי לעיין בדרישות האימות (דרוש מפתח API) וב נתוני השימוש ב-API והחיוב (צריך להפעיל את החיוב בפרויקט).

פרמטרים של כתובת אתר

כתובת URL של API סטטי של מפות Google חייבת להיות בפורמט הבא:

https://maps.googleapis.com/maps/api/staticmap?parameters

אם הגישה לאתר שלכם מתבצעת ב-HTTPS, עליכם לטעון תמונות של Maps Static API גם ב-HTTPS כדי להימנע מהתראות אבטחה של הדפדפן. מומלץ להשתמש ב-HTTPS גם אם הבקשות שלכם כוללות מידע רגיש על המשתמש, כמו מיקום המשתמש:

https://maps.googleapis.com/maps/api/staticmap?parameters

בין אם אתם משתמשים ב-HTTP או ב-HTTPS, יש כמה פרמטרים של כתובות URL שחובה לציין וכמה פרמטרים הם אופציונליים. כמקובל בכתובות URL, כל הפרמטרים מופרדים באמצעות תו האמפרסנד (&). במסמך הזה מפורטים רשימת הפרמטרים והערכים האפשריים שלהם.

ה-API של מפות סטטיות מגדיר תמונות מפה באמצעות הפרמטרים הבאים של כתובות אתרים:

פרמטרים של מיקום

  • center (חובה אם הסמנים לא קיימים) מגדיר את מרכז המפה, במרחק שווה מכל קצוות המפה. הפרמטר הזה מקבל מיקום בתור צמד {קו רוחב,קו אורך} שמופרד בפסיקים (למשל, 40.714728,-73.998672") או ככתובת מחרוזת (למשל "בניין עירייה, ניו יורק, ניו יורק") המזהה מיקום ייחודי על פני כדור הארץ. מידע נוסף זמין במאמר מיקומים.
  • zoom (חובה אם הסמנים לא קיימים) מגדיר את רמת הזום של המפה, שקובעת את רמת ההגדלה של המפה. הפרמטר הזה מקבל ערך מספרי שתואם לרמת הזום של האזור הרצוי. אפשר לקרוא מידע נוסף במאמר רמות הזום.

פרמטרים במפה

  • size (חובה) מגדיר את המידות המלבניות של תמונת המפה. הפרמטר הזה מקבל מחרוזת בפורמט {horizontal_value}x{vertical_value}. לדוגמה, 500x400 מגדיר מפה ברוחב 500 פיקסלים ובגובה 400 פיקסלים. במפות ברוחב של פחות מ-180 פיקסלים יוצג לוגו של Google מוקטן. הפרמטר הזה מושפע מהפרמטר scale. גודל הפלט הסופי הוא המכפלה של ערכי הגודל וקנה המידה.
  • scale (אופציונלי) משפיע על מספר הפיקסלים שמוחזרים. הפונקציה scale=2 מחזירה מספר כפול של פיקסלים מ- scale=1, תוך שמירה על אותו אזור כיסוי ורמת פירוט (כלומר, תוכן המפה לא משתנה). הדבר שימושי במהלך פיתוח למסכים ברזולוציה גבוהה. ערך ברירת המחדל הוא 1. הערכים הקבילים הם 1 ו-2. למידע נוסף, אפשר לקרוא את המאמר שינוי קנה המידה של הערכים.
  • format (אופציונלי) מגדיר את הפורמט של התמונה שתתקבל. כברירת מחדל, ה-API של מפות סטטיות יוצר תמונות PNG. יש כמה פורמטים אפשריים, כולל GIF , JPEG ו-PNG. הפורמט שבו תשתמשו תלוי באופן שבו אתם מתכוונים להציג את התמונה. פורמט JPEG בדרך כלל מספק דחיסה רבה יותר, ואילו קובצי GIF ו-PNG מספקים יותר פרטים. מידע נוסף זמין במאמר פורמטים של תמונות.
  • maptype (אופציונלי) מגדיר את סוג המפה שצריך ליצור. יש כמה ערכים אפשריים של סוג מפה, כולל roadmap, satellite, hybrid ו- terrain. מידע נוסף זמין במאמר סוגי מיפוי של API סטטי של מפות Google.
  • language (אופציונלי) מגדיר את השפה שבה ייעשה שימוש להצגת התוויות במשבצות המפה. לתשומת ליבכם: הפרמטר הזה נתמך רק בחלק מהמשבצות של המדינות. אם השפה הספציפית המבוקשת לא נתמכת בקבוצת המשבצות, המערכת תשתמש בשפת ברירת המחדל של קבוצת המשבצות הזו.
  • region (אופציונלי) מגדיר את הגבולות המתאימים להצגה על סמך רגישויות גיאו-פוליטיות. מקבל קוד אזור שצוין כערך של ccTLD (דומיין ברמה העליונה) בשני תווים. אפשר לקרוא מידע נוסף על האזורים הנתמכים בפרטי הכיסוי בפלטפורמה של מפות Google.

פרמטרים של תכונות

  • map_id (אופציונלי) מציין את המזהה של מפה ספציפית. מזהה המפה משייך את המפה לסגנון או לתכונה מסוימים, וצריך להשתייך לאותו פרויקט של מפתח ה-API שמשמש לאתחול המפה. מידע נוסף זמין במאמר שימוש במזהי מפות.
  • markers (אופציונלי) מגדיר סמן אחד או יותר לצירוף לתמונה במיקומים שצוינו. הפרמטר הזה משתמש בהגדרת סמן אחת עם פרמטרים המופרדים באמצעות קו אנכי (|). אפשר למקם סמנים מרובים בתוך אותו פרמטר markers, כל עוד הם מציגים אותו סגנון. ניתן להוסיף סמנים בסגנונות שונים על ידי הוספת פרמטרים של markers. חשוב לשים לב שאם מספקים סמנים למפה, אין צורך לציין את הפרמטרים center ו-zoom (הנדרשים בדרך כלל). מידע נוסף זמין במאמר סמנים של API סטטי של מפות Google.
  • path (אופציונלי) מגדיר נתיב יחיד של שתי נקודות מחוברות או יותר, שישמש כשכבת-על על התמונה במיקומים שצוינו. הפרמטר הזה מקבל מחרוזת של הגדרות נקודה שמופרדת באמצעות תו (|) או קו פוליגוני מקודד באמצעות הקידומת enc: בהצהרת המיקום של הנתיב. אפשר לספק נתיבים נוספים על ידי הוספת פרמטרים נוספים של path. חשוב לשים לב שאם מציינים נתיב למפה, אין צורך לציין את הפרמטרים center ו-zoom (הנדרשים בדרך כלל). מידע נוסף זמין במאמר נתיבי API סטטיים של מפות Google.
  • visible (אופציונלי) מציין מיקום אחד או יותר שצריכים להישאר גלויים במפה, למרות שלא יוצגו סמנים או אינדיקטורים אחרים. השתמש בפרמטר הזה כדי לוודא שתכונות מסוימות או מיקומים מסוימים במפות מוצגים ב- Maps Static API.
  • style (אופציונלי) מגדיר סגנון מותאם אישית כדי לשנות את ההצגה של תכונה ספציפית (כבישים, פארקים ותכונות אחרות) של המפה. הפרמטר הזה מקבל ארגומנטים מסוג feature ו-element שמזהים את התכונות של הסגנון, וכן קבוצה של פעולות סגנון שיש להחיל על התכונות שנבחרו. אפשר לספק מספר סגנונות על ידי הוספת פרמטרים נוספים של style. מידע נוסף זמין במדריך מפות מעוצבות.

פרמטרים של מפתחות וחתימה

  • באמצעות key (חובה) תוכלו לעקוב אחרי השימוש ב-API באפליקציה במסוף Google Cloud, וגם לוודא ש-Google תוכל ליצור איתכם קשר בנוגע לאפליקציה במקרה הצורך. מידע נוסף זמין במאמר שימוש במפתחות API עם Maps Static API.
  • signature (מומלץ) הוא חתימה דיגיטלית שמשמשת כדי לאמת שכל אתר שיוצר בקשות באמצעות מפתח ה-API שלך מורשה לעשות זאת. בקשות ללא חתימה דיגיטלית עשויות להיכשל. מידע נוסף זמין במאמר שימוש בחתימה דיגיטלית.

הגבלת גודל כתובת ה-URL

כתובות URL של API סטטי של מפות Google מוגבלות ל-16384 תווים. בפועל, סביר להניח שלא יהיה צורך בכתובות URL ארוכות יותר, אלא אם יוצרים מפות מורכבות עם מספר גבוה של סמנים ונתיבים.

שימוש בפרמטרים

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

ציון מיקומים

ל- Maps Static API חייב להיות יכולת לזהות בצורה מדויקת מיקומים במפה, גם כדי למקד את המפה במיקום הנכון (באמצעות הפרמטר center) ו/או כדי להציב סמנים אופציונליים (באמצעות הפרמטר markers) במיקומים במפה. כדי לציין את המיקומים האלו, ב- Maps Static API נעשה שימוש במספרים (ערכים של קווי רוחב ואורך) או במחרוזות (כתובות). הערכים האלה מזהים מיקום גיאוגרפי.

לכמה פרמטרים (כמו הפרמטרים markers ו-path) יש מספר מיקומים. במקרים האלה, המיקומים מופרדים באמצעות התו (|).

קווי אורך ורוחב

קווי אורך ורוחב מוגדרים באמצעות ספרות בתוך מחרוזת טקסט מופרדת בפסיקים, עם דיוק של 6 ספרות אחרי הנקודה העשרונית. לדוגמה, "40.714728,-73.998672" הוא ערך חוקי של קידוד גיאוגרפי. המערכת מתעלמת מדיוק מעבר ל-6 המקומות אחרי הנקודה העשרונית.

הערכים של קו האורך מבוססים על המרחק שלהם מגריניץ', אנגליה, שם המרידיאן הראשי. מכיוון שגרניץ' נמצאת בקו הרוחב 51.477222, אפשר להזין את הערך 51.477222,0 של center כדי למרכז את המפה בגריניץ':

גריניץ&#39;, אנגליה

הערכים של קווי האורך והרוחב חייבים להתאים למיקום חוקי על פני כדור הארץ. קווי רוחב יכולים לקבל כל ערך בין -90 ל-90, בעוד שערכי קווי אורך יכולים לקבל כל ערך בין -180 ל-180. אם תציינו ערכים לא תקינים של קווי אורך ורוחב, הבקשה תידחה כבקשה שגויה.

כתובות

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

בכל פרמטר שבו אפשר לציין קו אורך/רוחב, אפשר במקום זאת לציין מחרוזת שמציינת כתובת. Google תבצע קידוד גיאוגרפי של הכתובת ותספק לשירות ה-API הסטטי של מפות Google ערך של קווי אורך ורוחב לשימוש בהצבת סמנים או ציון מיקומים. המחרוזת צריכה להיות בקידוד כתובות URL, ולכן צריך להמיר כתובות כמו "City Hall, New York, NY" לדוגמה "עיר+הול, ניו+יורק, ניו יורק".

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

הדוגמה הבאה יוצרת תמונת מפה סטטית בברקלי, קליפורניה:

https://maps.googleapis.com/maps/api/staticmap?center=Berkeley,CA&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

ברקלי, קליפורניה

רמות מרחק התצוגה

במפות Google במפות Google יש 'רמת מרחק מתצוגה' במספר שלם שמגדיר את הרזולוציה של התצוגה הנוכחית. ניתן לראות רמות מרחק מתצוגה בין 0 (רמת המרחק מהתצוגה הנמוכה ביותר, שבה אפשר לראות את כל העולם במפה אחת) לבין 21+ (עד לרחובות ומבנים בודדים) בתצוגת ברירת המחדל roadmap. היכן שהדבר אפשרי, קווי מתאר של המבנים מופיעים במפה סביב מרחק התצוגה 17. הערך הזה משתנה מאזור לאזור, והוא עשוי להשתנות עם הזמן ככל שהנתונים מתפתחים.

במפות Google מתבצעת הגדרה של רמת הזום 0 כך שתקיף את כל כדור הארץ. כל רמה מצליחה של מרחק התצוגה מכפילה את הדיוק בממדים האופקיים והאנכיים. בתיעוד של JavaScript API במפות Google מוסבר איך עושים את זה.

הערה: לא כל רמות הזום מופיעות בכל המיקומים בכדור הארץ. רמות הזום משתנות בהתאם למיקום, כי בחלקים מסוימים של העולם הנתונים מפורטים יותר מאשר במיקומים אחרים.

אם תשלח בקשה לרמת התקרבות שבה לא קיימים קטעי מפה, ה-API הסטטי של מפות Google יחזיר במקום זאת תמונה ריקה.

ברשימה הבאה מוצגת רמת הפירוט המשוערת שניתן לראות בכל אחת מרמות המרחק מהתצוגה:

  • 1: עולם
  • 5: ארץ/יבשת
  • 10: עיר
  • 15: רחובות
  • 20: בניינים

בדוגמה הזו מוצגת בקשה לשתי מפות של מנהטן באותו ערך center, אבל ברמת התקרבות 12 ו-14, בהתאמה:

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

מנהטן פארוויי  מנהטן למעלה

גדלים של תמונות

הפרמטר size, יחד עם center, מגדיר את אזור הכיסוי של מפה. הוא גם מגדיר את גודל הפלט של המפה בפיקסלים, כשמכפלים אותו בערך scale (שהוא 1 כברירת מחדל).

בטבלה הזו מוצגים הערכים המקסימליים המותרים לפרמטר size בכל ערך של scale.

scale=1 scale=2
640x640 640x640 (מחזיר 1,280x1,280 פיקסלים)

בדוגמה הזו מופיעה בקשה ל "פרוסה" של כדור הארץ בקו המשווה ברמת זום 1:

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=400x50&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

קו המשווה

בדוגמה הזו מוצגת בקשה למפה קטנה, בגודל 100x100 פיקסלים, במרכז אותו אזור. שימו לב ללוגו הקטן יותר של Google:

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=100x100&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

מפת קו המשווה הקטן

שינוי קנה מידה

הפרמטר size של Maps Static API מגדיר את גודל המפה בפיקסלים, כך שמפה עם size=200x200 תוחזר כ-200 פיקסלים על 200 פיקסלים. בצג מחשב LCD, שבדרך כלל מציג כ-100 פיקסלים לאינץ' (ppi), מפה בגודל 200x200 תהיה בגודל של כ-2 אינץ' בכל ממד.

עם זאת, יותר ויותר מכשירים ניידים כוללים מסכים ברזולוציה גבוהה עם דחיסות פיקסלים של יותר מ-300ppi, במקרים הבאים:

  • יש להקטין את הגודל של תמונה בגודל 200x200 פיקסלים ל-0.7 אינץ' בלבד, התוויות והסמלים של עיבוד התמונה קטנים מדי לקריאה, או
  • יש לשנות את קנה המידה (מרחק התצוגה) של התמונה כדי לשפר את הקריאוּת שלה, והתוצאה היא תמונה מטושטשת או מפוקסלת.
קטן מדי התמונה לא ברורה מדי

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

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

150x150 150x150&scale=2

תמונה כזו תניב ביצועים טובים גם בדפדפנים במחשב, אם היא תוכנס לתג img או לתג div עם הגובה והרוחב שהוגדרו באמצעות CSS. הדפדפן יקטין את התמונה לגודל הנכון, בלי לגרוע מהאיכות.

בטבלה הזו מוצגות שלוש בקשות שונות לתמונה.

  • הראשונה היא לתמונה בגודל 100x100, ללא ציון ערך לגודל. הוא מוצג כראוי במחשב השולחני, אבל קטן מדי לקריאה במכשיר נייד.
  • השנייה מכפילה את גודל המפה. במחשב, ה-CSS מתאים אותו לרכיב img שצוין בגודל 100x100, אבל כשמקטינים את התמונה, הכבישים והתוויות הופכים קטנים מדי. בנייד, התמונה בגודל הנכון, אבל שוב, הדרכים והתוויות לא ניתנות לקריאה.
  • הבקשה השלישית היא למפה בגודל 100x100 עם scale=2. התמונה מוחזרת עם פירוט של 200 פיקסלים; במחשב השולחני, היא מוקטנת באופן מושלם, כך שלא ניתן להבחין בינה לבין הבקשה המקורית בגודל 100x100, והדפדפן בנייד נהנה מהרזולוציה הנוספת שמוחזרת על ידי ה-API.
בקשות תמונה
מכשיר 100x100 200x200 100x100&scale=2
מחשב
(עם height="100px" ו-
width="100px" בתג
img)
רזולוציה גבוהה
(סימולציה)

למידע נוסף על פיתוח לצגים ברזולוציה גבוהה וניידים, מומלץ לקרוא את המאמרים הבאים:

פורמטים של תמונות

התמונות עשויות להיות מוחזרות בכמה פורמטים נפוצים של גרפיקה באינטרנט: GIF, JPEG ו-PNG. הפרמטר format מקבל אחד מהערכים הבאים:

  • השדה png8 או png (ברירת המחדל) מציין את פורמט PNG של 8 סיביות.
  • png32 מציין את פורמט PNG של 32 סיביות.
  • השדה gif מציין את הפורמט GIF.
  • השדה jpg מציין את פורמט הדחיסה JPEG.
  • jpg-baseline מציין פורמט דחיסה JPEG לא פרוגרסיבי.

בדוגמאות הבאות מוצגות מפות בפורמט gif ובפורמט png:

  https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&format=gif&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
  https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&format=png&&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

jpg ו-jpg-baseline בדרך כלל מספקים את גודל התמונה הקטן ביותר, אבל הם עושים זאת באמצעות דחיסת נתונים מסוג 'lossy', שעלולה לפגוע בתמונה. gif, png8 ו-png32 מספקים דחיסה ללא אובדן נתונים.

רוב התמונות בפורמט JPEG הן הדרגתיות, כלומר הן טוענות תמונה גסה יותר מוקדם יותר ומצמצמות את רזולוציית התמונה ככל שמגיעים נתונים נוספים. כך אפשר לטעון תמונות במהירות בדפי אינטרנט, ונכון לעכשיו השימוש הנפוץ ביותר ב-JPEG. עם זאת, לשימושים מסוימים ב-JPEG יש צורך בתמונות לא פרוגרסיביות (בסיסיות). במקרים כאלה, כדאי להשתמש בפורמט jpg-baseline, שאינו הדרגתי.

סוגי מפות

ה-API הסטטי של מפות Google יוצר מפות בכמה פורמטים, כמפורט בהמשך:

  • roadmap (ברירת מחדל) מציין תמונה סטנדרטית של מפת דרכים, כפי שמוצג בדרך כלל באתר של מפות Google. אם לא מצוין ערך maptype, ה-API הסטטי של מפות Google יציג roadmap משבצות כברירת מחדל.
  • satellite מציין תמונת לוויין.
  • terrain מציין תמונה של מפת תבליט פיזי, שמציגה את פני השטח וצמחייה.
  • hybrid מציין שילוב בין תמונת הלוויין לבין תמונת מפת הדרכים, שמציג שכבה שקופה של רחובות ראשיים ושמות של מקומות בתמונת הלוויין.

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

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=roadmap&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

מפה רגילה של מנהטן  מפת פני השטח של מנהטן

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

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=hybrid&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

מפת הלוויין של מנהטן  מפת פני השטח של מנהטן

מפות מסוגננות

התאימו אישית את ההצגה של מפת Google הרגילה על ידי החלת סגנונות משלכם. מומלץ לעיין במדריך למפות מעוצבות.

סמנים

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

הפרמטר markers מקבל את הקבוצה של הקצאות הערכים (מתארי סמנים) בפורמט הבא:

markers=markerStyles|markerLocation1| markerLocation2|... וכו'

הקבוצה של markerStyles מוצהרת בתחילת ההצהרה markers והיא כוללת אפס תיאורי סגנון או יותר שמופרדים באמצעות קו אנכי (|), ואחריה קבוצה של מיקום אחד או יותר שמופרדים גם באמצעות קו אנכי (|).

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

סגנונות עט סימון

קבוצת מתארי סגנון הסמנים היא סדרה של הקצאות ערכים שמופרדות באמצעות התו (|). מתאר הסגנון הזה מגדיר את המאפיינים החזותיים שבהם צריך להשתמש להצגת הסמנים במתאר הסמנים הזה. מתארי הסגנון האלה כוללים את ההקצאות של מפתח/ערך:

  • size: (אופציונלי) מציין את גודל הסמן מתוך הקבוצה {tiny, mid, small}. אם לא הוגדר פרמטר size, הסמן יופיע בגודל ברירת המחדל (רגיל).

  • color: (אופציונלי) מציין צבע של 24 ביט (לדוגמה: color=0xFFFFCC) או צבע מוגדר מראש מהקבוצה {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

    חשוב לשים לב ששקפים (שמצוינים באמצעות ערכי צבע הקסדצימליים של 32 סיביות) לא נתמכים בסמנים, אבל הם נתמכים לנתיבים.

  • label: (אופציונלי) מציין תו אלפאנומרי uppercase מתוך הקבוצה {A-Z, 0-9}. (דרישה לתווים באותיות רישיות היא דרישה חדשה בגרסה הזו של ה-API). לתשומת ליבך, סמני ברירת המחדל וסמני בגודל mid הם הסמנים היחידים שיכולים להציג פרמטר alphanumeric-character. הסמנים tiny ו-small לא יכולים להציג תו אלפאנומרי.

שינוי גודל הסמן

הערך של scale מוכפל בגודל תמונת הסמן כדי להפיק את גודל הפלט בפועל של הסמן בפיקסלים. ערך ברירת המחדל לסולם הוא 1, והערכים הקבילים הם 1, 2 ו-4.

מגבלת גודל הפיקסלים על תמונות חלה אחרי החלת השינוי. לדוגמה, אם הסמן מוגדר לערך scale:2, הסמן יכול להיות גדול יותר מהגודל המקסימלי של 4,096 פיקסלים, כל עוד הוא יורד לפחות מ-4,096 פיקסלים לאחר השינוי. שימוש בשינוי קנה מידה של סמנים בשילוב עם שינוי קנה מידה במפה כשמציגים מפות ברזולוציה גבוהה יותר.

מיקומי סמנים

כל מתאר של סמן צריך להכיל קבוצה של מיקום אחד או יותר המגדירים את המיקום של הסמן במפה. אפשר לציין את המיקומים האלה כערכי קו רוחב/קו אורך או ככתובות. המיקומים האלה מופרדים באמצעות התו (|).

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

הפרמטרים של המיקום מגדירים את מיקום הסמן במפה. אם המיקום לא מופיע במפה, הסמן לא יופיע בתמונה המובנית בתנאי שהפרמטרים center ו-zoom סופקו. עם זאת, אם לא תספקו את הפרמטרים האלה, שרת ה-API של מפות הסטטיות של מפות Google ייצור באופן אוטומטי תמונה שמכילה את הסמנים שסופקו. (פרטים נוספים זמינים במאמר מיקום משתמע.)

כאן מוצגת הצהרת סמנים לדוגמה. שימו לב שאנחנו מגדירים קבוצה אחת של סגנונות ושלושה מיקומים:

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&size=400x400&
markers=color:blue%7Clabel:S%7C11211%7C11206%7C11222&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

שלושה מיקודים בברוקלין

כדי להגדיר סמנים עם סגנונות שונים, אנחנו צריכים לספק מספר פרמטרים של markers. קבוצת הפרמטרים הזו של markers מגדירה שלושה סמנים: סמן כחול אחד עם התווית "S" ב-62.107733, -145.5419, סמן ירוק זעיר ב-"Delta Junction, AK", מסמן צהוב אחד בגודל "C" ב-"Tok, AK". הסמנים הבאים מוצגים בדוגמה הבאה:

https://maps.googleapis.com/maps/api/staticmap?center=63.259591,-144.667969&zoom=6&size=400x400
&markers=color:blue%7Clabel:S%7C62.107733,-145.541936&markers=size:tiny%7Ccolor:green%7CDelta+Junction,AK
&markers=size:mid%7Ccolor:0xFFFF00%7Clabel:C%7CTok,AK"&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

שלוש עיירות באלסקה, סמנים שונים

סמלים מותאמים אישית

במקום להשתמש בסמלי הסמנים של Google, תוכלו להשתמש במקום זאת בסמלים מותאמים אישית משלכם. סמלים מותאמים אישית מצוינים באמצעות התיאור icon בפרמטר markers. למשל:

markers=icon:URLofIcon|markerLocation

מציינים את icon באמצעות כתובת URL (שצריכה להיות מקודדת בכתובת URL). אפשר להשתמש בכתובות URL שנוצרו על ידי שירותים לקיצור כתובות URL כמו https://goo.gl. היתרון של רוב שירותי הקיצור של כתובות URL הוא קידוד אוטומטי של כתובות URL.

ניתן לציין נקודת עוגן עבור הסמל המותאם אישית. נקודת העוגן קובעת את אופן מיקום הסמל ביחס למיקומים שצוינו ב-markers. כברירת מחדל, נקודת העוגן של סמל מותאם אישית נמצאת במרכז החלק התחתון של תמונת הסמל. אפשר לציין נקודת עוגן אחרת באמצעות התיאור anchor בשילוב עם icon. מגדירים את anchor כנקודת x,y של הסמל (למשל 10,5) או כיישור מוגדר מראש באמצעות אחד מהערכים הבאים: top, bottom, left, right, center, topleft, topright, bottomleft או bottomright. למשל:

markers=anchor:bottomright|icon:URLofIcon|markerLocation1|markerLocation2

ניתן להשתמש בעד חמישה סמלים ייחודיים מותאמים אישית בכל בקשה. המשמעות של ההגבלה הזו היא שאתם מוגבלים ל-5 מיקומים מסומנים בלבד במפה. ניתן להשתמש בכל סמל ייחודי עם יותר ממיקום markers אחד במפה.

פורמט הסמל:

  • תמונות סמלים יכולות להיות בפורמט PNG, JPEG או GIF, אך מומלץ להשתמש ב-PNG.
  • הגודל המרבי של סמלים הוא 4,096 פיקסלים (64x64 עבור תמונות ריבועיות).
דוגמאות לסמלים מותאמים אישית

דוגמה 1 יוצרת סמלים מותאמים אישית וממקמת את הסמלים באמצעות עוגנים.

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=anchor:32,10%7Cicon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=anchor:topleft%7Cicon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=anchor:topright%7Cicon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY
&signature=YOUR_SIGNATURE

שלוש עיירות באוסטרליה, סמלים שונים בהתאמה אישית ממוקמים עם עוגנים.

דוגמה 2 יוצרת את אותם סמלים מותאמים אישית כמו בדוגמה 1, אבל לא מגדירה את מיקומי הסמלים באמצעות עוגנים, בהתאם לעוגן המוגדר כברירת מחדל במרכז החלק התחתון.

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=icon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=icon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=icon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

שלוש עיירות באוסטרליה, סמלים שונים בהתאמה אישית עם מיקום ברירת המחדל.

נתיבי API סטטי של מפות Google

הפרמטר path מגדיר קבוצה של מיקום אחד או יותר, שמחוברים באמצעות נתיב לשכבת-על בתמונת המפה. הפרמטר path מקבל קבוצה של הקצאות ערכים (תיאורי נתיב) בפורמט הבא:

path=pathStyles|pathLocation1|pathLocation2|... וכו'

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

סגנונות נתיב

קבוצה של מתארי סגנון נתיב היא סדרה של הקצאות ערכים שמופרדות באמצעות התו (|). מתאר הסגנון הזה מגדיר את המאפיינים החזותיים שבהם צריך להשתמש בהצגת הנתיב. מתארי הסגנונות האלה מכילים את ההקצאות הבאות של מפתחות/ערכים:

  • weight: (אופציונלי) מציין את עובי הנתיב בפיקסלים. אם לא הוגדר פרמטר weight, הנתיב יופיע בעובי ברירת המחדל שלו (5 פיקסלים).

  • color: (אופציונלי) מציין צבע כערך הקסדצימלי של 24 ביט (לדוגמה: color=0xFFFFCC) או של 32 ביט (לדוגמה: color=0xFFFFCCFF), או כערך הקסדצימלי של {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

    כשמצוין ערך הקסדצימלי של 32 ביט, שני התווים האחרונים מציינים את ערך השקיפות של אלפא 8 ביט. הערך הזה משתנה בין 00 (שקוף לחלוטין) לבין FF (אטום לחלוטין). חשוב לשים לב ששקפים נתמכים בנתיבים, אבל הם לא נתמכים עבור סמנים.

  • fillcolor: (אופציונלי) מציין שהנתיב מסמן אזור פוליגון וגם מציין את צבע המילוי שבו ייעשה שימוש כשכבה כשכבת-על בתוך האזור הזה. קבוצת המיקומים הבאה לא חייבת להיות לולאה "סגורה" . השרת של Maps Static API יצטרף באופן אוטומטי לנקודה הראשונה ולנקודה האחרונה. עם זאת, שימו לב שכל שרטוט בחלק החיצוני של האזור שהוזן לא ייסגר, אלא אם ציינתם באופן ספציפי את אותו מיקום התחלה וסיום.
  • geodesic: (אופציונלי) מציין שיש לפרש את הנתיב המבוקש כקו גיאודזי בהתאם לעקמומיות של כדור הארץ. אם הערך הוא False, הנתיב מעובד כקו ישר בשטח המסך. ברירת המחדל היא False.

כמה הגדרות של נתיבים לדוגמה:

  • קו כחול דק, 50% אטימות: path=color:0x0000ff80|weight:1
  • קו אדום מלא: path=color:0xff0000ff|weight:5
  • קו לבן עבה מלא: path=color:0xffffffff|weight:10

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

נקודות בנתיב

כדי לשרטט נתיב, צריך להעביר גם שתי נקודות או יותר מהפרמטר path. לאחר מכן, ה-API הסטטי של מפות Google יחבר את הנתיב לאורך הנקודות האלה, לפי הסדר שנקבע. כל pathPoint מסומן ב-pathDescriptor, ומופרד בתו | (pipe).

בדוגמה הבאה מוגדר נתיב כחול עם ברירת מחדל של 50% אטימות מ-Union Square NY ל-Time Square, NY.

נתיב מ-Union Sq ל-Times Sq

הפרטים הספציפיים של הפרמטר path:

path=color:0x0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

בדוגמה הבאה מוגדר אותו נתיב, במקום להגדיר קו אדום מלא עם שקיפות של 100%:

נתיב מ-Union Sq ל-Times Sq

הפרטים הספציפיים של הפרמטר path הזה:

path=color:0xff0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

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

נתיב מ-Union Sq ל-Times Sq

הפרטים הספציפיים של הפרמטר path הזה:

path=color:0x00000000|weight:5|fillcolor:0xFFFF0033|8th+Avenue+%26+34th+St,New+York,NY|\
8th+Avenue+%26+42nd+St,New+York,NY|Park+Ave+%26+42nd+St,New+York,NY,NY|\
Park+Ave+%26+34th+St,New+York,NY,NY

שימו לב שאנחנו מגדירים את הנתיב עצמו כמוסתר, ושאזור הפוליגונים יהיה אטימוּת של 15%.

קווים מרובים מקודדים

במקום סדרה של מיקומים, אפשר להצהיר על נתיב כקו מרובה נקודות מקודד באמצעות הקידומת enc: בהצהרת המיקום של path.

הדוגמה הבאה מתארת את המסלול של הכביש המהיר של אלסקה מדוסון קריק, קרוין לצומת הדלתא, AK, עם קו פוליגוני מקודד:

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=59.900503,-135.478011&zoom=4
&path=weight:3%7Ccolor:orange%7Cenc:_fisIp~u%7CU}%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA}f[roaAynd@%7CvXxiAt{ZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k{g@i`]o%7CF}vXaj\h`]ovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh`]v%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez\_{Km_`@~re@ew^rcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr{ZlwBrvdAmtHrmT{rOt{Zz}E%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@``NrfQpcHrb^k%7CDh_z@nwB%7Ckb@a{R%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY}t]huf@e%7CFria@o}GfezAkdW%7C}[ocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C`l@uoJrvdAgq@fppAsjGhg`@%7ChQpg{Ai_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C}[mv`@t_NitSfjp@c}Mhg`@sbChyYq}e@rwg@atFff}@ghN~zKybk@fl}A}cPftcAite@tmT__Lha@u~DrfQi}MhkSqyWivIumCria@ciO_tHifm@fl}A{rc@fbjAqvg@rrqAcjCf%7Ci@mqJtb^s%7C@fbjA{wDfs`BmvEfqs@umWt_Nwn^pen@qiBr`xAcvMr{Zidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

כביש מהיר אלסקה

כמו בנתיבים רגילים, גם נתיבים פוליגונים מקודדים יכולים לסמן אזורים פוליגונים אם ארגומנט fillcolor מועבר לפרמטר path.

הדוגמה הבאה מציגה אזור פוליגון עבור ברוקלין, ניו יורק:

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=40.653279,-73.959816&zoom=11
&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:}zswFtikbMjJzZ%7CRdPfZ}DxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz@bIx{A%7CPfYlvApz@bl@tcAdTpGpVwQtX}i@%7CGen@lCeAda@bjA%60q@v}@rfAbjA%7CEwBpbAd_@he@hDbu@uIzWcWtZoTdImTdIwu@tDaOXw_@fc@st@~VgQ%7C[uPzNtA%60LlEvHiYyLs^nPhCpG}SzCNwHpz@cEvXg@bWdG%60]lL~MdTmEnCwJ[iJhOae@nCm[%60Aq]qE_pAaNiyBuDurAuB }}Ay%60@%7CEKv_@?%7C[qGji@lAhYyH%60@Xiw@tBerAs@q]jHohAYkSmW?aNoaAbR}LnPqNtMtIbRyRuDef@eT_z@mW_Nm%7CB~j@zC~hAyUyJ_U{Z??cPvg@}s@sHsc@_z@cj@kp@YePoNyYyb@_iAyb@gBw^bOokArcA}GwJuzBre@i\tf@sZnd@oElb@hStW{]vv@??kz@~vAcj@zKa%60Atf@uQj_Aee@pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

ברוקלין מקודד Polyline עם חתימה

אזורי תצוגה

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

בדוגמה הבאה מוצגת בקשה למפה שבמרכזה בוסטון, מסצ'וסטס, המכילה את MIT ואת כיכר הרווארד בקיימברידג', מסצ'וסטס:

https://maps.googleapis.com/maps/api/staticmap?center=Boston,MA
&visible=77+Massachusetts+Ave,Cambridge,MA%7CHarvard+Square,Cambridge,MA&size=512x512&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

מפת קיימברידג&#39;

מיקום מרומז של המפה

בדרך כלל עליכם לציין פרמטרים של כתובת אתר מסוג center ו-zoom כדי להגדיר את המיקום ואת רמת המרחק מהתצוגה של המפה שנוצרה. עם זאת, אם תספקו את הפרמטרים markers, path או visible, תוכלו במקום זאת לאפשר ל-Maps Static API לקבוע את המרחק הנכון ואת המרחק מהתצוגה באופן מרומז, על סמך הערכת המיקום של הרכיבים האלה.

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

https://maps.googleapis.com/maps/api/staticmap?size=512x512&maptype=roadmap\
&markers=size:mid%7Ccolor:red%7CSan+Francisco,CA%7COakland,CA%7CSan+Jose,CA&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

מפת דרכים

תמונות גדולות יותר

אם יש לכם צורך בתמונות גדולות מ- 640 x 640 פיקסלים (או 1280 x 1,280 פיקסלים עם ערך גודל של 2), תוכלו לפנות לצוות התמיכה ולצרף את הפרטים הבאים:

  1. תרחיש לדוגמה שלכם והסיבה לכך שאתם צריכים תמונות גדולות.
  2. האם אתם שוקלים להשתמש בממשקי API אחרים של הפלטפורמה של מפות Google (API של מפות Google, API של מפות Google, SDK של מפות Google ל-Android או SDK של מפות Google ל-iOS), ומדוע הם לא תואמים לצרכים שלכם.
  3. צילומי מסך, הדמיות או דוגמאות של האופן שבו תשתמשו בתמונות בגודל גדול.
  4. השימוש החודשי המשוער שלך בתמונות בגודל גדול.

אנחנו נבדוק את הבקשה על סמך המידע שנקבל מכם ונחליט אם התרחיש לדוגמה שלכם תואם לתנאים ולהגבלות של הפלטפורמה של מפות Google.

הגודל המקסימלי שאנחנו יכולים לספק הוא 2,048 x 2,048 פיקסלים.

תמיכה ופתרון בעיות

למידע נוסף על השימוש ב-Maps Static API, אפשר לעיין בדף התמיכה.

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