diff --git a/specification/maps/data-plane/Microsoft.Maps/Render/preview/1.0/render.json b/specification/maps/data-plane/Microsoft.Maps/Render/preview/1.0/render.json index 3fe229eaf2f9..3832e1a0218e 100644 --- a/specification/maps/data-plane/Microsoft.Maps/Render/preview/1.0/render.json +++ b/specification/maps/data-plane/Microsoft.Maps/Render/preview/1.0/render.json @@ -266,7 +266,7 @@ "/map/static/{format}": { "get": { "x-publish": true, - "description": "**Applies to**: S0 and S1 pricing tiers.\n\n\nThe static image service renders a user-defined, rectangular image containing a map section using a zoom level from 0 to 20. The static image service renders a user-defined, rectangular image containing a map section using a zoom level from 0 to 20. The supported resolution range for the map image is from 1x1 to 8192x8192. If you are deciding when to use the static image service over the map tile service, you may want to consider how you would like to interact with the rendered map. If the map contents will be relatively unchanging, a static map is a good choice. If you want to support a lot of zooming, panning and changing of the map content, the map tile service would be a better choice. \n\nService also provides Image Composition functionality to get a static image back with additional data like; pushpins and geometry overlays with following S0 and S1 capabilities. \n\nIn S0 you can:\n- Render up to 5 pushpins specified in the request\n- Provide one custom image for the pins referenced in the request\n- Add labels to the pushpins\n\nIn S1 you can:\n- Render pushpins through [Azure Maps Data Service](https://aka.ms/AzureMapsMapDataService)\n- Specify multiple pushpin styles\n- Provide custom pushpin images stored in [Azure Maps Data Service](https://aka.ms/AzureMapsMapDataService)\n- Render circle, polyline and polygon geometry types.\n- Render of supported GeoJSON geometry types uploaded through [Azure Maps Data Service](https://aka.ms/AzureMapsMapDataService)\n\nPlease see [How-to-Guide](https://aka.ms/AzureMapsHowToGuideImageCompositor) for detailed examples.\n\n_Note_ : Either **center** or **bbox** parameter must be supplied to the\nAPI.\n

\nThe supported Lat and Lon ranges when using the **bbox** parameter, are as follows:\n

\n\n |Zoom Level | Max Lon Range | Max Lat Range|\n |:----------|:----------------|:-------------|\n |0 | 360.0 | 170.0 | \n |1 | 360.0 | 170.0 |\n |2 | 360.0 | 170.0 |\n |3 | 360.0 | 170.0 |\n |4 | 360.0 | 170.0 |\n |5 | 180.0 | 85.0 |\n |6 | 90.0 | 42.5 |\n |7 | 45.0 | 21.25 |\n |8 | 22.5 | 10.625 |\n |9 | 11.25 | 5.3125 |\n |10 | 5.625 | 2.62625 |\n |11 | 2.8125 | 1.328125 |\n |12 | 1.40625 | 0.6640625 |\n |13 | 0.703125 | 0.33203125 |\n |14 | 0.3515625 | 0.166015625 |\n |15 | 0.17578125 | 0.0830078125 | \n |16 | 0.087890625 | 0.0415039063 | \n |17 | 0.0439453125 | 0.0207519531 |\n |18 | 0.0219726563 | 0.0103759766 |\n |19 | 0.0109863281 | 0.0051879883 |\n |20 | 0.0054931641 | 0.0025939941 |", + "description": "**Applies to**: S0 and S1 pricing tiers.\n\n\nThe static image service renders a user-defined, rectangular image containing a map section using a zoom level from 0 to 20. The static image service renders a user-defined, rectangular image containing a map section using a zoom level from 0 to 20. The supported resolution range for the map image is from 1x1 to 8192x8192. If you are deciding when to use the static image service over the map tile service, you may want to consider how you would like to interact with the rendered map. If the map contents will be relatively unchanging, a static map is a good choice. If you want to support a lot of zooming, panning and changing of the map content, the map tile service would be a better choice. \n\nService also provides Image Composition functionality to get a static image back with additional data like; pushpins and geometry overlays with following S0 and S1 capabilities. \n\nIn S0 you can:\n- Render up to 5 pushpins specified in the request\n- Provide one custom image for the pins referenced in the request\n- Add labels to the pushpins\n\nIn S1 you can:\n- Render pushpins through [Azure Maps Data Service](https://aka.ms/AzureMapsMapDataService)\n- Specify multiple pushpin styles\n- Render circle, polyline and polygon geometry types.\n- Render of supported GeoJSON geometry types uploaded through [Azure Maps Data Service](https://aka.ms/AzureMapsMapDataService)\n\nPlease see [How-to-Guide](https://aka.ms/AzureMapsHowToGuideImageCompositor) for detailed examples.\n\n_Note_ : Either **center** or **bbox** parameter must be supplied to the\nAPI.\n

\nThe supported Lat and Lon ranges when using the **bbox** parameter, are as follows:\n

\n\n |Zoom Level | Max Lon Range | Max Lat Range|\n |:----------|:----------------|:-------------|\n |0 | 360.0 | 170.0 | \n |1 | 360.0 | 170.0 |\n |2 | 360.0 | 170.0 |\n |3 | 360.0 | 170.0 |\n |4 | 360.0 | 170.0 |\n |5 | 180.0 | 85.0 |\n |6 | 90.0 | 42.5 |\n |7 | 45.0 | 21.25 |\n |8 | 22.5 | 10.625 |\n |9 | 11.25 | 5.3125 |\n |10 | 5.625 | 2.62625 |\n |11 | 2.8125 | 1.328125 |\n |12 | 1.40625 | 0.6640625 |\n |13 | 0.703125 | 0.33203125 |\n |14 | 0.3515625 | 0.166015625 |\n |15 | 0.17578125 | 0.0830078125 | \n |16 | 0.087890625 | 0.0415039063 | \n |17 | 0.0439453125 | 0.0207519531 |\n |18 | 0.0219726563 | 0.0103759766 |\n |19 | 0.0109863281 | 0.0051879883 |\n |20 | 0.0054931641 | 0.0025939941 |", "operationId": "Render_GetMapImage", "x-ms-examples": { "GetMapStaticImage": { @@ -398,7 +398,7 @@ }, { "name": "pins", - "description": "Pushpin style and instances. Use this parameter to optionally add pushpins to the image.\nThe pushpin style describes the appearance of the pushpins, and the instances specify\nthe coordinates of the pushpins and optional labels for each pin. (Be sure to properly URL-encode values of this\nparameter since it will contain reserved characters such as pipes and punctuation.)\n\nThe Azure Maps account S0 SKU only supports a single instance of the pins parameter. Other SKUs\nallow multiple instances of the pins parameter to specify multiple pin styles.\n\nTo render a pushpin at latitude 45°N and longitude 122°W using the default built-in pushpin style, add the\nquerystring parameter \n\n`pins=default||-122 45` \n\nNote that the longitude comes before the latitude.\nAfter URL encoding this will look like\n\n`pins=default%7C%7C-122+45`\n\nAll of the examples here show the pins\nparameter without URL encoding, for clarity.\n\nTo render a pin at multiple locations, separate each location with a pipe character. For example, use\n\n`pins=default||-122 45|-119.5 43.2|-121.67 47.12`\n\nThe S0 Azure Maps account SKU only allows five pushpins. Other account SKUs do not have this limitation.\n\n### Style Modifiers\n\nYou can modify the appearance of the pins by adding style modifiers. These are added after the style but before\nthe locations and labels. Style modifiers each have a two-letter name. These abbreviated names are used to help\nreduce the length of the URL.\n\nTo change the color of the pushpin, use the 'co' style modifier and specify the color using the HTML/CSS RGB color\nformat which is a six-digit hexadecimal number (the three-digit form is not supported). For example, to use\na deep pink color which you would specify as #FF1493 in CSS, use\n\n`pins=default|coFF1493||-122 45`\n\n### Pushpin Labels\n\nTo add a label to the pins, put the label in single quotes just before the coordinates. For example, to label\nthree pins with the values '1', '2', and '3', use\n\n`pins=default||'1'-122 45|'2'-119.5 43.2|'3'-121.67 47.12`\n\nThere is a built in pushpin style called 'none' that does not display a pushpin image. You can use this if\nyou want to display labels without any pin image. For example,\n\n`pins=none||'A'-122 45|'B'-119.5 43.2`\n\nTo change the color of the pushpin labels, use the 'lc' label color style modifier. For example, to use pink\npushpins with black labels, use\n\n`pins=default|coFF1493|lc000000||-122 45`\n\nTo change the size of the labels, use the 'ls' label size style modifier. The label size represents the approximate\nheight of the label text in pixels. For example, to increase the label size to 12, use\n\n`pins=default|ls12||'A'-122 45|'B'-119 43`\n\nThe labels are centered at the pushpin 'label anchor.' The anchor location is predefined for built-in pushpins and\nis at the top center of custom pushpins (see below). To override the label anchor, using the 'la' style modifier\nand provide X and Y pixel coordinates for the anchor. These coordinates are relative to the top left corner of the\npushpin image. Positive X values move the anchor to the right, and positive Y values move the anchor down. For example,\nto position the label anchor 10 pixels right and 4 pixels above the top left corner of the pushpin image,\nuse\n\n`pins=default|la10 -4||'A'-122 45|'B'-119 43`\n\n### Custom Pushpins\n\nTo use a custom pushpin image, use the word 'custom' as the pin style name, and then specify a URL after the\nlocation and label information. Use two pipe characters to indicate that you're done specifying locations and are\nstarting the URL. For example,\n\n`pins=custom||-122 45||http://contoso.com/pushpins/red.png`\n\nAfter URL encoding, this would look like\n\n`pins=custom%7C%7C-122+45%7C%7Chttp%3A%2F%2Fcontoso.com%2Fpushpins%2Fred.png`\n\nBy default, custom pushpin images are drawn centered at the pin coordinates. This usually isn't ideal as it obscures\nthe location that you're trying to highlight. To override the anchor location of the pin image, use the 'an'\nstyle modifier. This uses the same format as the 'la' label anchor style modifier. For example, if your custom\npin image has the tip of the pin at the top left corner of the image, you can set the anchor to that spot by\nusing\n\n`pins=custom|an0 0||-122 45||http://contoso.com/pushpins/red.png`\n\nNote: If you use the 'co' color modifier with a custom pushpin image, the specified color will replace the RGB \nchannels of the pixels in the image but will leave the alpha (opacity) channel unchanged. This would usually\nonly be done with a solid-color custom image.\n\n### Getting Pushpins from Azure Maps Data Storage\n\nFor all Azure Maps account SKUs other than S0,\nthe pushpin image and location information can be obtained from Azure Maps Data Storage. After uploading a pushpin image\nor a GeoJSON document containing pin locations, the Data Storage service returns a Unique Data ID (UDID) that you can use\nto reference the data in the pins parameter.\n\nTo use a custom pushpin image from Azure Maps Data Storage, specify the UDID prefixed by 'udid-' as the name of the\npushpin style. For example,\n\n`pins=udid-fe22c504-3a81-4fcd-adc6-a3507ce866c1||-122 45`\n\nTo use the point geometry from an uploaded GeoJSON document as the pin locations, specify the UDID in the locations\nsection of the pins parameter. For example,\n\n`pins=default||udid-29dc105a-dee7-409f-a3f9-22b066ae4713`\n\nNote that\nonly point and multipoint geometry, points and multipoints from geometry collections, and point geometry from features\nwill be used. Linestring and polygon geometry will be ignored. If the point comes from a feature and the feature\nhas a string property called \"label\", the value of that property will be used as the label for the pin.\n\nYou can mix pin locations from Data Storage and pin locations specified in the pins parameter. Any of the pipe-delimited\npin locations can be a longitude and latitude or a UDID. For example,\n\n`pins=default||-122 45|udid-29dc105a-dee7-409f-a3f9-22b066ae4713|-119 43`\n\n### Scale, Rotation, and Opacity\n\nYou can make pushpins and their labels larger or smaller by using the 'sc' scale style modifier. This is a\nvalue greater than zero. A value of 1 is the standard scale. Values larger than 1 will make the pins larger, and\nvalues smaller than 1 will make them smaller. For example, to draw the pushpins 50% larger than normal, use\n\n`pins=default|sc1.5||-122 45`\n\nYou can rotate pushpins and their labels by using the 'ro' rotation style modifier. This is a number of degrees\nof clockwise rotation. Use a negative number to rotate counter-clockwise. For example, to rotate the pushpins\n90 degrees clockwise and double their size, use\n\n`pins=default|ro90|sc2||-122 45`\n\nYou can make pushpins and their labels partially transparent by specifying the 'al' alpha style modifier.\nThis is a number between 0 and 1 indicating the opacity of the pushpins. Zero makes them completely transparent\n(and not visible) and 1 makes them completely opaque (which is the default). For example, to make pushpins\nand their labels only 67% opaque, use\n\n`pins=default|al.67||-122 45`\n\n### Style Modifier Summary\n\nModifier | Description | Range \n:--------:|-----------------|------------------\nal | Alpha (opacity) | 0 to 1 \nan | Pin anchor | * \nco | Pin color | 000000 to FFFFFF \nla | Label anchor | * \nlc | Label color | 000000 to FFFFFF \nls | Label size | Greater than 0 \nro | Rotation | -360 to 360 \nsc | Scale | Greater than 0 \n\n* X and Y coordinates can be anywhere within pin image or a margin around it.\nThe margin size is the minimum of the pin width and height.", + "description": "Pushpin style and instances. Use this parameter to optionally add pushpins to the image.\nThe pushpin style describes the appearance of the pushpins, and the instances specify\nthe coordinates of the pushpins and optional labels for each pin. (Be sure to properly URL-encode values of this\nparameter since it will contain reserved characters such as pipes and punctuation.)\n\nThe Azure Maps account S0 SKU only supports a single instance of the pins parameter. Other SKUs\nallow multiple instances of the pins parameter to specify multiple pin styles.\n\nTo render a pushpin at latitude 45°N and longitude 122°W using the default built-in pushpin style, add the\nquerystring parameter \n\n`pins=default||-122 45` \n\nNote that the longitude comes before the latitude.\nAfter URL encoding this will look like\n\n`pins=default%7C%7C-122+45`\n\nAll of the examples here show the pins\nparameter without URL encoding, for clarity.\n\nTo render a pin at multiple locations, separate each location with a pipe character. For example, use\n\n`pins=default||-122 45|-119.5 43.2|-121.67 47.12`\n\nThe S0 Azure Maps account SKU only allows five pushpins. Other account SKUs do not have this limitation.\n\n### Style Modifiers\n\nYou can modify the appearance of the pins by adding style modifiers. These are added after the style but before\nthe locations and labels. Style modifiers each have a two-letter name. These abbreviated names are used to help\nreduce the length of the URL.\n\nTo change the color of the pushpin, use the 'co' style modifier and specify the color using the HTML/CSS RGB color\nformat which is a six-digit hexadecimal number (the three-digit form is not supported). For example, to use\na deep pink color which you would specify as #FF1493 in CSS, use\n\n`pins=default|coFF1493||-122 45`\n\n### Pushpin Labels\n\nTo add a label to the pins, put the label in single quotes just before the coordinates. For example, to label\nthree pins with the values '1', '2', and '3', use\n\n`pins=default||'1'-122 45|'2'-119.5 43.2|'3'-121.67 47.12`\n\nThere is a built in pushpin style called 'none' that does not display a pushpin image. You can use this if\nyou want to display labels without any pin image. For example,\n\n`pins=none||'A'-122 45|'B'-119.5 43.2`\n\nTo change the color of the pushpin labels, use the 'lc' label color style modifier. For example, to use pink\npushpins with black labels, use\n\n`pins=default|coFF1493|lc000000||-122 45`\n\nTo change the size of the labels, use the 'ls' label size style modifier. The label size represents the approximate\nheight of the label text in pixels. For example, to increase the label size to 12, use\n\n`pins=default|ls12||'A'-122 45|'B'-119 43`\n\nThe labels are centered at the pushpin 'label anchor.' The anchor location is predefined for built-in pushpins and\nis at the top center of custom pushpins (see below). To override the label anchor, using the 'la' style modifier\nand provide X and Y pixel coordinates for the anchor. These coordinates are relative to the top left corner of the\npushpin image. Positive X values move the anchor to the right, and positive Y values move the anchor down. For example,\nto position the label anchor 10 pixels right and 4 pixels above the top left corner of the pushpin image,\nuse\n\n`pins=default|la10 -4||'A'-122 45|'B'-119 43`\n\n### Custom Pushpins\n\nTo use a custom pushpin image, use the word 'custom' as the pin style name, and then specify a URL after the\nlocation and label information. Use two pipe characters to indicate that you're done specifying locations and are\nstarting the URL. For example,\n\n`pins=custom||-122 45||http://contoso.com/pushpins/red.png`\n\nAfter URL encoding, this would look like\n\n`pins=custom%7C%7C-122+45%7C%7Chttp%3A%2F%2Fcontoso.com%2Fpushpins%2Fred.png`\n\nBy default, custom pushpin images are drawn centered at the pin coordinates. This usually isn't ideal as it obscures\nthe location that you're trying to highlight. To override the anchor location of the pin image, use the 'an'\nstyle modifier. This uses the same format as the 'la' label anchor style modifier. For example, if your custom\npin image has the tip of the pin at the top left corner of the image, you can set the anchor to that spot by\nusing\n\n`pins=custom|an0 0||-122 45||http://contoso.com/pushpins/red.png`\n\nNote: If you use the 'co' color modifier with a custom pushpin image, the specified color will replace the RGB \nchannels of the pixels in the image but will leave the alpha (opacity) channel unchanged. This would usually\nonly be done with a solid-color custom image.\n\n### Getting Pushpins from Azure Maps Data Storage\n\nFor all Azure Maps account SKUs other than S0,\nthe pushpin location information can be obtained from Azure Maps Data Storage. After uploading a GeoJSON document containing pin locations, the Data Storage service returns a Unique Data ID (UDID) that you can use\nto reference the data in the pins parameter.\n\nTo use the point geometry from an uploaded GeoJSON document as the pin locations, specify the UDID in the locations\nsection of the pins parameter. For example,\n\n`pins=default||udid-29dc105a-dee7-409f-a3f9-22b066ae4713`\n\nNote that\nonly point and multipoint geometry, points and multipoints from geometry collections, and point geometry from features\nwill be used. Linestring and polygon geometry will be ignored. If the point comes from a feature and the feature\nhas a string property called \"label\", the value of that property will be used as the label for the pin.\n\nYou can mix pin locations from Data Storage and pin locations specified in the pins parameter. Any of the pipe-delimited\npin locations can be a longitude and latitude or a UDID. For example,\n\n`pins=default||-122 45|udid-29dc105a-dee7-409f-a3f9-22b066ae4713|-119 43`\n\n### Scale, Rotation, and Opacity\n\nYou can make pushpins and their labels larger or smaller by using the 'sc' scale style modifier. This is a\nvalue greater than zero. A value of 1 is the standard scale. Values larger than 1 will make the pins larger, and\nvalues smaller than 1 will make them smaller. For example, to draw the pushpins 50% larger than normal, use\n\n`pins=default|sc1.5||-122 45`\n\nYou can rotate pushpins and their labels by using the 'ro' rotation style modifier. This is a number of degrees\nof clockwise rotation. Use a negative number to rotate counter-clockwise. For example, to rotate the pushpins\n90 degrees clockwise and double their size, use\n\n`pins=default|ro90|sc2||-122 45`\n\nYou can make pushpins and their labels partially transparent by specifying the 'al' alpha style modifier.\nThis is a number between 0 and 1 indicating the opacity of the pushpins. Zero makes them completely transparent\n(and not visible) and 1 makes them completely opaque (which is the default). For example, to make pushpins\nand their labels only 67% opaque, use\n\n`pins=default|al.67||-122 45`\n\n### Style Modifier Summary\n\nModifier | Description | Range \n:--------:|-----------------|------------------\nal | Alpha (opacity) | 0 to 1 \nan | Pin anchor | * \nco | Pin color | 000000 to FFFFFF \nla | Label anchor | * \nlc | Label color | 000000 to FFFFFF \nls | Label size | Greater than 0 \nro | Rotation | -360 to 360 \nsc | Scale | Greater than 0 \n\n* X and Y coordinates can be anywhere within pin image or a margin around it.\nThe margin size is the minimum of the pin width and height.", "in": "query", "required": false, "type": "array",