Yandex.Maps Static API Developer's guide 15.05.2015 Yandex.Maps Static API. Developer's guide. Version 1.0 Document build date: 15.05.2015. This volume is a part of Yandex technical documentation. Yandex helpdesk site: http://help.yandex.ru © 2008—2015 Yandex LLC. All rights reserved. Copyright Disclaimer Yandex (and its applicable licensor) has exclusive rights for all results of intellectual activity and equated to them means of individualization, used for development, support, and usage of the service Yandex.Maps Static API. It may include, but not limited to, computer programs (software), databases, images, texts, other works and inventions, utility models, trademarks, service marks, and commercial denominations. The copyright is protected under provision of Part 4 of the Russian Civil Code and international laws. You may use Yandex.Maps Static API or its components only within credentials granted by the Terms of Use of Yandex.Maps Static API or within an appropriate Agreement. Any infringements of exclusive rights of the copyright owner are punishable under civil, administrative or criminal Russian laws. Contact information Yandex LLC http://www.yandex.com Phone: +7 495 739 7000 Email: [email protected] Headquarters: 16 L'va Tolstogo St., Moscow, Russia 119021 Contents About this document ............................................................................................................................................................................ 4 Overview of the Static API .................................................................................................................................................................. 4 Map center ........................................................................................................................................................................................... 5 Map size ............................................................................................................................................................................................... 6 Viewport .............................................................................................................................................................................................. 7 Zoom level ........................................................................................................................................................................................... 8 Map layers and types ........................................................................................................................................................................... 9 Traffic ................................................................................................................................................................................................ 12 Placemarks ......................................................................................................................................................................................... 12 Lines and polygons ............................................................................................................................................................................ 16 Automatic map positioning ................................................................................................................................................................ 20 Map localization ................................................................................................................................................................................. 22 Index .................................................................................................................................................................................................. 23 Yandex.Maps Static API Developer's guide Developer's guide About this document This guide is a detailed reference for the Yandex.Maps Static API. It explains the flow for working with the API, summarizes all the URL parameters, and describes each parameter in detail with working examples. The guide is intended for website developers who want to use static images from Yandex.Maps on their web pages. Overview of the Static API The Static API generates a map image based on the parameter values passed to the service in a URL with the following format: http://static-maps.yandex.ru/1.x/?lang=en-US&{URL parameters} The substring {URL parameters} contains a sequence of pairs in the format {parameter name}={parameter value}, separated by the ampersand symbol (&). The following example is a request for a map image of the center of Ankara with two numbered markers: http://static-maps.yandex.ru/1.x/?lang=en-US&ll=32.810152,39.889847& \ size=450,450&z=10&l=map&pt=32.810152,39.889847,pm2rdl1~32.870152,39.869847,pm2rd l99 Attention! Line breaks in the examples are indicated with backslash symbols ( \ ), which you should remove when copying the examples into your web page HTML code or your browser address string. The complete list of URL parameters is shown below. Parameter Data type and example Description l string,[string]... List of layers that define the type of map: map (roadmap), sat (satellite) and sat,skl (hybrid). Mandatory parameter. For more information, see Map layers and types. l=map Yandex.Maps Static API Developer's guide 4 Developer's guide Parameter Data type and example Description ll float,float Longitude and latitude of the map center in degrees; see Map center. ll=32.810152,39.889847 spn float spn=0.01,0.01 z integer Range of the map's viewport by longitude and latitude (in degrees); see Viewport. Zoom level of the map (0-17); see Zoom level. z=10 size integer,integer size=450,450 pt Height and width of the requested map image (in pixels); see Map size. string Contains definitions of one or more markers to be displayed on the (MarkerDefinition1~Mark map. erDefinition2~...) Each marker definition contains its coordinates (longitude pt=32.810152,39.889847,pm and latitude) along with information on its appearance (including 2rdl1~32.870152,39.869847 style, color, size and the marker text). Marker definitions ,pm2rdl99 are separated by a tilda (~). For more information, see Placemarks. pl string Contains definitions of geometric figures (polylines and polygons) (FigureDefinition1~Figu to display on the map. reDefinition2~...) The figure definition contains coordinates for its points (either a comma-separated list, or encoded), along with information on line pl=c:ec473fFF,f: 00FF00A0,w:5, \ color and thickness, and the fill color (for polygons). Figure 37.51,55.83,37.67,55.82,3 definitions are separated by a tilda (~). 7.66,55.74, \ 37.49,55.70,37.51,55.83 lang string (languageregion) lang=en-US For more information, see Lines and polygons Locale. • language — Two-letter language code. Specified in ISO 639-1 format. • region — Two-letter country code. Specified in ISO 3166-1 format. The following locales are currently supported: • lang=ru-RU • lang=tr-TR • lang=en-US For more information, see Map localization. Map center The center of the map image is set in the ll parameter. Its longitude and latitude (in degrees) are set off by commas in the parameter. The ll parameter is used either with the spn parameter (viewport), or with the z parameter (zoom level). Yandex.Maps Static API Developer's guide 5 Developer's guide Tip: 1. The map center usually shows a specific object of interest (building, city, etc.). To find an object's geographical coordinates by its address or name, you can use the Yandex.Maps geocoding service. 2. On the Yandex.Maps page the browser address bar shows a URL with the necessary parameters for displaying the map fragment that you see on the screen. These parameters include the coordinates of the object found via search (the sll parameter), the coordinates of the map center (the ll parameter), and the map viewport (the spn parameter). You can use the values of these parameters to request a static image of a map fragment. Attention! If the ll parameter is not set, the Static API automatically positions the map. The request example below is for a map image centered at 6. Sokak, Ehlibeyt, Çankaya, Ankara. The values for the map center and the viewport were determined using Yandex.Maps (the query "6. Sokak, Ehlibeyt, Çankaya, Ankara"). http://static-maps.yandex.ru/1.x/?lang=en-US&ll=32.810152,39.889847 \ &spn=0.016457,0.00619&l=map Map size The size of the map display is set using the size parameter, where the height and width of the map (in pixels) are separated by a comma. The maximum size allowed for the map display is 650x450 pixels. The examples below show requests for maps sized 450x150 and 200x200 pixels, centered on Istanbul with a zoom level of z=9: http://static-maps.yandex.ru/1.x/?lang=en-US&ll=28.98824,41.043451&z=9&l=map \ &size=450,150 Yandex.Maps Static API Developer's guide 6 Developer's guide http://static-maps.yandex.ru/1.x/lang=en-US&?ll=28.98824,41.043451&z=9&l=map \ &size=200,200 Viewport The viewport is the minimal area shown surrounding the map center. The viewport is set using the spn parameter, using a comma to set off its range, which is specified by longitude and latitude (in degrees). The Static API selects the appropriate zoom level so that the entire specified area is visible on the image. Attention! If the spn parameter is not set, and the zoom level is not set explicitly, the Static API attempts to set the omitted parameters automatically. Examples The examples below show map image requests that differ from each other only by the viewport size (0.02x0.02, 0.3x0.3 and 10x10 degrees). The requested map fragment is centered on Taksim Meydanı in Istanbul, and the map size is 300x300 pixels. Viewport of 0.02x0.02 degrees: http://static-maps.yandex.ru/1.x/?lang=enUS&ll=28.98513,41.036943&spn=0.002,0.002 \ &size=300,300&l=map Viewport of 0.3x0.3 degrees: Yandex.Maps Static API Developer's guide 7 Developer's guide http://static-maps.yandex.ru/1.x/lang=en-US&?ll=28.98513,41.036943&spn=0.3,0.3 \ &size=300,300&l=map Viewport of 10x10 degrees: http://static-maps.yandex.ru/1.x/lang=en-US&?ll=28.98513,41.036943&spn=10,10 \ &size=300,300&l=map Zoom level The zoom level determines the current resolution of the image from the map. In the Static API, the zoom level is set by the z parameter, which can take whole values from 0 to 17. At the zero zoom level, the map shows the entire world, while at the maximum zoom level, it shows a single building. When the zoom level is increased by a single level, the image resolution doubles; for more information, see Coordinates and projections. Note: If the request specifies a viewport (the spn parameter), the zoom level is ignored. Attention! Not all zoom levels are available in all areas of the map. If the requested zoom level is not available for the selected area, the map will not be returned. The example below is a request for a map image with zoom level 12, centered on Sultanahmet Camii: http://static-maps.yandex.ru/1.x/?lang=en-US&ll=28.97709,41.005233&z=12 \ &size=450,450&l=map Yandex.Maps Static API Developer's guide 8 Developer's guide The following example is a request for the same map, but with the maximum zoom level (17): http://static-maps.yandex.ru/1.x/?lang=enUS&ll=28.97709,41.005233&z=17&size=450,450&l=map Map layers and types The map image consists of one or more layers overlaid on each other. The list of layers is set in the "l" parameter (the bottom layer should be listed first). Layer Image format Description map PNG Map of an area with names of geographical objects. sat JPG A satellite photo of the area. skl PNG Names of geographical objects. trf PNG Traffic jams layer. Yandex.Maps Static API Developer's guide 9 Developer's guide Layers can be combined. The available map types ("Roadmap," "Satellite" or "Hybrid") each correspond to a layer or specific combination of layers: • map — "Roadmap" map type. • sat — "Satellite" map type. • sat, skl — "Hybrid" map type. Examples for each map type are provided below: Roadmap (l=map) Map of the center of Istanbul: http://static-maps.yandex.ru/1.x/?lang=en-US&ll=28.98824,41.043451 \ &spn=0.1,0.1&l=map Roadmap showing traffic (l=map,trf,skl) Roadmap of the center of Istanbul showing traffic: http://static-maps.yandex.ru/1.x/lang=en-US&?ll=28.98824,41.043451 \ &spn=0.1,0.1&l=map,trf,skl Yandex.Maps Static API Developer's guide 10 Developer's guide Satellite (l=sat) Satellite map of the center of Istanbul: http://static-maps.yandex.ru/1.x/lang=en-US&?ll=28.98824,41.043451 \ &spn=0.1,0.1&l=sat Hybrid (l=sat,skl) Hybrid map of the center of Istanbul (the map framework is on the "satellite" layer): http://static-maps.yandex.ru/1.x/lang=en-US&?ll=28.98824,41.043451 \ &spn=0.1,0.1&l=sat,skl Hybrid map showing traffic (l=sat,trf,skl) Hybrid map of the center of Istanbul showing traffic: http://static-maps.yandex.ru/1.x/lang=en-US&?ll=28.98824,41.043451 \ &spn=0.1,0.1&l=sat,trf,skl Yandex.Maps Static API Developer's guide 11 Developer's guide Traffic In addition to the standard map types, you can add an additional traffic layer to a map to show traffic levels in a city. To display the traffic layer, specify trf in the list of layers in the l parameter. Example roadmap of the center of Ankara with a traffic layer: http://static-maps.yandex.ru/1.x/?lang=en-US&ll=32.84243,39.948244 \ &spn=0.1,0.1&l=map,trf Placemarks The pt parameter is for displaying one or more placemarks (up to 100) on the map image: pt=PlacemarkDefinition1~PlacemarkDefinition2~PlacemarkDefinition3... Yandex.Maps Static API Developer's guide 12 Developer's guide Each placemark definition contains its coordinates (longitude and latitude) along with information on its appearance (including style, color, size and content of the placemark). The placemark definition uses the following pattern: {longitude},{latitude},{style}{color}{size}{content} Rules for designating placemarks: Style Color pm Description Size: wt — white do — dark orange • s — small • m — medium • l — large Content: db — dark blue bl — blue • For the sizes s and m, a number from 1 to 99. • For the l size, a number from 1 to 100. gn — green gr — grey lb — light blue nt — night or- orange pn — pink rd — red vv — violet yw — yellow a — with the letter "A" (without specifying content or size) b — with the letter "B" (without specifying content or size) Yandex.Maps Static API Developer's guide 13 Developer's guide Style Color Description Size: pm2 wt — white • m — medium • l — large Content: do — dark orange Number from 1 to 99. db — dark blue bl — blue gn — green dg — dark green gr — grey lb — light blue nt — night or- orange pn — pink rd — red vv — violet yw — yellow a — with the letter "A" (without specifying content) Yandex.Maps Static API Developer's guide 14 Developer's guide Style Color Description b — with the letter "B" (without specifying content) org — blue (without specifying content) dir — violet (without specifying content) blyw — blue with a yellow dot flag — flag. vk Size: m — medium bk- black button Content is not specified. gr — grey button Note: By ( default, a white medium-sized placemark is used pmwtm ). Example The request example below is for an image of a map fragment with placemarks of various styles, colors and sizes: http://static-maps.yandex.ru/1.x/?lang=en-US&l=map& \ pt=28.98624,41.043451~28.95624,41.043451,78~28.94114,41.043451, \ pmgrs~28.98124,41.043451,pm2rdm~28.97624,41.043451, \ pmntl100~28.965573,41.04311,pmors23~28.950111,41.043451, \ flag~28.969573,41.04311,pm2ywl99 Yandex.Maps Static API Developer's guide 15 Developer's guide If the placemark coordinates fall outside of the specified viewport, the placemark is not shown on the map. The placemark will also not be shown if the text has invalid symbols (anything other than numbers from 1 to 99). See also Automatic map positioning Lines and polygons Polylines and polygons can be used on a static map to mark a route or the boundaries of an object. A polyline consists of a set of points connected by straight line segments. A polyline can cross itself. If the coordinates of the first and last points are the same, the polyline is called a closed polyline. A polygon is set using one or more closed polylines. Restriction: The Static API allows displaying no more than 5 polylines and polygons on a map at once, and the total number of points on figures cannot be more than 100. The outward appearance of a geometric figure is set using a special definition. The polyline definition contains information about the thickness and color of lines, while the polygon definition contains information about the thickness and color of the outline and the fill color (see below). The points on all figures are assigned geographical coordinates. The point coordinates and the outward appearance of polylines and polygons are set using the pl parameter. This parameter contains definitions for all the figures displayed on the map. Figure definitions are separated by a tilda (~): pl = FigureDefinition1~FigureDefinition2~FigureDefinition3 The polyline definition has the following format: c:{line color},w:{thickness},{points} The polygon definition can additionally contain the fill color (the f parameter): Yandex.Maps Static API Developer's guide 16 Developer's guide c:{line color},f:{fill color},w:{thickness},{points} Line color An RGBA hex string (0xFFFFFFFF format) represents the line color. The first 6 symbols set the RGB color, and the next two set the line transparency. The transparency value has a range from 00 (transparent) to FF (opaque). For example: c:8822DDC0 Polygon fill color Uses the same format as the polyline color (see above). For example: f:00FF00A0 The even-odd rule is used for filling a polygon. This means that a point is filled in if a ray drawn from that point to infinity has an odd number of intersections with the edges of the polygon. An area where several polygons intersect is always filled in. Thickness Line thickness (in pixels). w:8 Note: If color and thickness are not set, a light violet semitransparent line with a thickness of 5 pixels is used (8822DDC0). Points The point coordinates of a polyline are set Longitude1,Latitude2,...,LongitudeN,LatitudeN. in the following way: The point coordinates of a polygon created by a single closed polyline are set in the same way. To define a polygon using a set of closed polylines, a semicolon must be used to separate the sequence of points for each polyline: PolylinePointCoordinates1;...PolylinePointCoordinates2. Examples • Polyline • Polygon defined by a single polyline • Polygon defined by a set of polylines • Intersecting polygons Polyline The request example below is for a map fragment of Izmir with an image of the pedestrian route from the "Çankaya" metro station to the Turkiye Tarim Kredi Kooperatifleri building. The polyline points are set by a list of point coordinates, and the default color and thickness are used: Yandex.Maps Static API Developer's guide 17 Developer's guide http://static-maps.yandex.ru/1.x/?lang=en-US&l=map \ &pl=27.135483,38.422478,27.137685,38.422469,27.137736,38.422564,27.137789,38.424 045,27.138519,38.423975,27.141899,38.423802, \ 27.142215,38.423756,27.142333,38.423697,27.142376,38.423549, \ 27.142596,38.423368,27.142971,38.423347,27.143285,38.423625, \ 27.143245,38.423912,27.143015,38.424102,27.142795,38.424128, \ 27.142795,38.424128,27.142387,38.423918,27.141909,38.423918, \ 27.138275,38.42422 Polygon defined by a single polyline The request example below is for a map fragment of Izmir with the walls of the "İzmir Fuarı" marked on it. It uses a polygon with a red outline and light green semitransparent fill to define the boundaries of the fortress: http://static-maps.yandex.ru/1.x/?lang=en-US&l=map \ &pl=c:ec473fFF,f:00FF00A0,w:7,27.14325,38.43178, \ 27.14855,38.430419,27.149794,38.428225,27.147327,38.425693, \ 27.147305,38.424562,27.143142,38.424089,27.141426,38.427853, \ 27.14325,38.43178 Yandex.Maps Static API Developer's guide 18 Developer's guide Polygon defined by a set of polylines The example below is for a map that displays a polygon defined by a set of polylines. The polyline point coordinates are separated by a semicolon. http://static-maps.yandex.ru/1.x/?lang=en-US&l=map \ &pl=f:30d5c844,w:7,29.085258,41.018105,29.100278, \ 41.016024,29.097618,41.007508,29.086545,41.009978, \ 29.085258,41.018105;29.089893,41.014724,29.096759, \ 41.013814,29.096158,41.010303,29.091009,41.011669, \ 29.089893,41.014724 Intersecting polygons The example below is for a map that displays two intersecting polygons. The set of parameters for each polygon is separated by a tilda (~). The area where the polygons intersect is filled in. http://static-maps.yandex.ru/1.x/?lang=en-US&l=map \ &pl=f:2222DDC0,c:003399,29.088504,41.052278,29.097001,\ 41.042141,29.08756,41.044935,29.088504,41.052278~ \ c:00ff0055,f:3caa3c77,29.100434,41.048444,29.086187, \ 41.04643,29.089791,41.042076,29.100434,41.048444 Yandex.Maps Static API Developer's guide 19 Developer's guide See also Automatic map positioning Automatic map positioning If the map image has at least one placemark or geometric figure (polyline or polygon), the viewport can be automatically selected, even if the URL does not specify values for the map center (ll parameter), the viewport (spn parameter), or the zoom level (z parameter). The Static API selects values for the omitted parameters so that all placemarks, polylines and polygons are visible on the map. If there is only one placemark set, it will be the center of the map; if a single polyline or polygon is set, the map center will be the geometric center of the area that is formed by the points of this polyline or polygon. The example below shows a request for a map fragment of Ankara that has a pedestrian path drawn on it from from the "Çankaya" metro station to the Turkiye Tarim Kredi Kooperatifleri building (there are placemarks at the beginning and end of the route). The request does not specify the ll, z or spn parameters: http://static-maps.yandex.ru/1.x/?lang=en-US&l=map \ &pt=27.135483,38.422478,pm2am~27.138275,38.42422, \ pm2bm&pl=27.135483,38.422478,27.137685,38.422469, \ 27.137736,38.422564,27.137789,38.424045,27.138519, \ 38.423975,27.141899,38.423802,27.142215,38.423756, \ 27.142333,38.423697,27.142376,38.423549,27.142596, \ 38.423368,27.142971,38.423347,27.143285,38.423625, \ 27.143245,38.423912,27.143015,38.424102,27.142795, \ 38.424128,27.142795,38.424128,27.142387,38.423918, \ 27.141909,38.423918,27.138275,38.42422 Yandex.Maps Static API Developer's guide 20 Developer's guide If we add another placemark to the map, for example, at the Kadifekale a different map center and zoom level will be selected: http://static-maps.yandex.ru/1.x/?lang=en-US&l=map \ &pt=27.135483,38.422478,pm2am~27.138275,38.42422, \ pm2bm~27.14316,38.416435,pm2vvl&pl=27.135483,38.422478, \ 27.137685,38.422469,27.137736,38.422564,27.137789, \ 38.424045,27.138519,38.423975,27.141899,38.423802, \ 27.142215,38.423756,27.142333,38.423697,27.142376, \ 38.423549,27.142596,38.423368,27.142971,38.423347, \ 27.143285,38.423625,27.143245,38.423912,27.143015, \ 38.424102,27.142795,38.424128,27.142795,38.424128, \ 27.142387,38.423918,27.141909,38.423918,27.138275,38.42422 See also Placemarks Lines and polygons Yandex.Maps Static API Developer's guide 21 Developer's guide Map localization The Static.API lets you make localized map images with labels in different languages. To set the language for geo object names on a map, you need to pass the locale in the HTTP request. The locale is set in RFC-3066 format using the lang parameter: lang=language-region • language — Two-letter language code. Specified in ISO 639-1 format. • region — Two-letter country code. Specified in ISO 3166-1 format. The following locales are currently supported: • lang=ru-RU • lang=tr-TR • lang=en-US Note: Turkish on geo object labels is currently supported only for maps of Turkey. The example below is for a map of Moscow with labels in Russian: http://static-maps.yandex.ru/1.x/?lang=ru-RU&l=map&ll=37.620070,55.753630&z=10 Yandex.Maps Static API Developer's guide 22 Index map center 5 map layer 12 map layers 9 map size 6 map type 9 Roadmap placemark color 12 placemark size 12 placemark style 12 placemark text 12 placemarks 12 style polygon fill color 16 polygon outline color 16 polygon outline thickness 16 polygons 16 fill color polyline color 16 polyline thickness 16 polylines 16 color traffic 12 URL parameters 4–9, 12, 16 key viewport 7 zoom level 8 Yandex.Maps Static API Developer's guide Yandex.Maps Static API Developer's guide 15.05.2015
© Copyright 2024