תחילת עבודה

מפתחים באזור הכלכלי האירופי (EEA)

מבוא

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

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

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

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

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

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

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

כתובת URL של Maps Static API צריכה להיות בפורמט הבא:

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, כל הפרמטרים מופרדים באמצעות התו אמפרסנד (&). רשימת הפרמטרים והערכים האפשריים שלהם מפורטים במסמך הזה.

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

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

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

פרמטרים של מפה

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

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

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

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

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

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

כתובות ה-URL של Maps Static API מוגבלות ל-16,384 תווים. בפועל, סביר להניח שלא תצטרכו כתובות URL ארוכות יותר, אלא אם אתם יוצרים מפות מורכבות עם מספר גבוה של סמנים ונתיבים.

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

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

ציון מיקומים

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

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

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

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

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

גריניץ', אנגליה

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

כתובות

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

בכל פרמטר שבו אפשר לציין קו רוחב או קו אורך, אפשר גם לציין מחרוזת שמציינת כתובת. ‫Google תמיר את הכתובת לקואורדינטות ותספק לשירות Maps Static API ערך של קו רוחב/קו אורך, כדי להשתמש בו להצבת סמנים או לציון מיקומים. המחרוזת צריכה להיות מקודדת בכתובת URL, כך שכתובות כמו "City Hall, New York, NY" צריכות להיות מומרות ל-"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 Maps יש מספר שלם שנקרא "רמת זום", שמגדיר את הרזולוציה של התצוגה הנוכחית. בתצוגת ברירת המחדל של roadmap אפשר להגדיר רמות זום בין 0 (רמת הזום הנמוכה ביותר, שבה אפשר לראות את כל העולם במפה אחת) לבין 21+ (עד לרמת הרחובות והבניינים הבודדים). קווי המתאר של מבנים, אם הם זמינים, מופיעים במפה ברמת זום של 17 בערך. הערך הזה משתנה מאזור לאזור ויכול להשתנות עם הזמן ככל שהנתונים מתפתחים.

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

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

אם תשלחו בקשה לרמת זום שאין בה משבצות מפה, Maps Static API יחזיר תמונה ריקה.

ברשימה הבאה מוצגת רמת הפירוט המשוערת שאפשר לצפות לראות בכל רמת זום:

  • ‫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, שהוא לא פרוגרסיבי.

סוגי מפות

‫Maps Static API יוצר מפות בכמה פורמטים, שמפורטים בהמשך:

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

בדוגמת הקוד הבאה אפשר לראות את ההבדל בין סוגי המפות roadmap ו-terrain.

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

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

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

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

מיקומי הסמנים

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

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

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

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

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

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

נתיבים ב-Maps Static API

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

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

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

סגנונות של נתיבים

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

  • ‫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 שתי נקודות או יותר. לאחר מכן, Maps Static API יחבר את המסלול לאורך הנקודות האלה, בסדר שצוין. כל pathPoint מצוין ב-pathDescriptor ומופרד באמצעות התו | (קו אנכי).

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

מסלול מכיכר יוניון לכיכר טיימס

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

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

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

מסלול מיוניון סקוור לטיימס סקוור

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

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

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

מסלול מכיכר יוניון לכיכר טיימס

הפרטים של הפרמטר 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.

בדוגמה הבאה מתואר המסלול של כביש אלסקה מ-Dawson Creek, BC ל-Delta Junction, 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%7D%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA%7Df%5BroaAynd@%7CvXxiAt%7BZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k%7Bg@i%60%5Do%7CF%7DvXaj%5Ch%60%5Dovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh%60%5Dv%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez%5C_%7BKm_%60@~re@ew%5ErcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr%7BZlwBrvdAmtHrmT%7BrOt%7BZz%7DE%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@%60%60NrfQpcHrb%5Ek%7CDh_z@nwB%7Ckb@a%7BR%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY%7Dt%5Dhuf@e%7CFria@o%7DGfezAkdW%7C%7D%5BocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C%60l@uoJrvdAgq@fppAsjGhg%60@%7ChQpg%7BAi_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C%7D%5Bmv%60@t_NitSfjp@c%7DMhg%60@sbChyYq%7De@rwg@atFff%7D@ghN~zKybk@fl%7DA%7DcPftcAite@tmT__Lha@u~DrfQi%7DMhkSqyWivIumCria@ciO_tHifm@fl%7DA%7Brc@fbjAqvg@rrqAcjCf%7Ci@mqJtb%5Es%7C@fbjA%7BwDfs%60BmvEfqs@umWt_Nwn%5Epen@qiBr%60xAcvMr%7BZidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Alaska Highway

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

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

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=40.653279,-73.959816&zoom=11
&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:%7DzswFtikbMjJzZ%7CRdPfZ%7DDxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz%40bIx%7BA%7CPfYlvApz%40bl%40tcAdTpGpVwQtX%7Di%40%7CGen%40lCeAda%40bjA%60q%40v%7D%40rfAbjA%7CEwBpbAd_%40he%40hDbu%40uIzWcWtZoTdImTdIwu%40tDaOXw_%40fc%40st%40~VgQ%7C%5BuPzNtA%60LlEvHiYyLs%5EnPhCpG%7DSzCNwHpz%40cEvXg%40bWdG%60%5DlL~MdTmEnCwJ%5BiJhOae%40nCm%5B%60Aq%5DqE_pAaNiyBuDurAuB%7D%7DAy%60%40%7CEKv_%40%3F%7C%5BqGji%40lAhYyH%60%40Xiw%40tBerAs%40q%5DjHohAYkSmW%3FaNoaAbR%7DLnPqNtMtIbRyRuDef%40eT_z%40mW_Nm%7CB~j%40zC~hAyUyJ_U%7BZ%3F%3FcPvg%40%7Ds%40sHsc%40_z%40cj%40kp%40YePoNyYyb%40_iAyb%40gBw%5EbOokArcA%7DGwJuzBre%40i%5Ctf%40sZnd%40oElb%40hStW%7B%5Dvv%40%3F%3Fkz%40~vAcj%40zKa%60Atf%40uQj_Aee%40pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

קו פוליגוני מקודד של ברוקלין עם חתימה

אזורי תצוגה

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

בדוגמה הבאה נבקש מפה שמתמקדת בבוסטון, מסצ'וסטס, ומכילה גם את 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

מפת קיימברידג'

מיקום משתמע של המפה

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

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

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 פיקסלים (או ‎1,280 x 1,280 פיקסלים עם ערך קנה מידה של 2), פנו לצוות התמיכה וציינו את הפרטים הבאים:

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

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

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

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

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

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