You are here: Using REST > v2006 services > REST v2006 mapping

REST v2006 mapping

With the ArcWeb Services implementation of REST, you make direct calls to the API through a Web browser. Create a URL that contains all the mapping criteria you want and get back a map. See Parameters for descriptions of the parameters you can use to make your map request.

How to generate a map through REST

To start using REST with ArcWeb Services, you need an active subscription to ArcWeb Services . Then, you need an authentication token to verify you are authorized to access ArcWeb Services. There are two ways to request an authentication token, using getToken or using getUserID. Most ArcWeb requests, whether using a UserID or a token, consume credits from a user account. See Understanding credits and costs for more information.

UserIDs do not expire and they are not bound to the IP address of a client machine. This allows a REST request containing a UserID to be shared between multiple users. Every request with a UserID will be charged to the account that issued the UserID regardless of who sends the request. You can only have one UserID per account. ESRI recommends using UserIDs only during phases of development and testing, when they offer more flexibility and convenience. We recommend that you change your account password which invalidates any existing UserIDs, and switch to using tokens before making an application public.

It is highly recommended that you use the getToken request since the returned token has an expiration (default 60 minutes) while a token from a getUserID request does not expire. An expiration helps minimize the negative impact of a malicious client stealing and trying to reuse the authentication token to access ArcWeb Services. Also note that a UserID changes when the password is changed.

Using getToken

Send an HTTP GET or HTTP POST request for a token that validates you as an authorized ArcWeb user. If your user name and password are valid, you get a token to use in your map request. See the Authentication parameter for details about sending a token request.
https://www.arcwebservices.com/services/v2006/restmap?actn=getToken&usr=<username>&pswd=<password>
Send a map request. See Parameters for the different options you have for building your map. See Projections for map projection parameters and information. The following URL represents an example of the required parameters for requesting a map. Every map request must include a token (tkn) or userID (usrid), data source (ds), center point (c), and scale factor (sf). See the Map parameter for details on these required parameters.
http://www.arcwebservices.com/services/v2006/restmap?actn=getMap&tkn=<token generated in step 1>&ds=ArcWeb:TA.Streets.NA&c=-117.1817|34.0556&sf=52500

See Sample requests for a variety of URL sample requests you can use to help you create REST maps.

Using getUserID

Warning: If a token from a getUserID request is hacked and hijacked, it can be used to consume your ArcWeb credits. This can be stopped by changing your password, which changes your UserID, invalidating the previous one, or you can disable the UserID feature on the ArcWeb UserID account page.

Send an HTTP GET or HTTP POST request for a UserID that validates you as an authorized ArcWeb user. If your user name and password are valid, you get a UserID to use in your map request. See the Authentication parameter for details about sending a getUserID request.
https://arcwebservices.com/services/v2006/restmap?actn=getUserID&usr=<username>&pswd=<password>
Send a map request. See Parameters for the different options you have for building your map. See Projections for map projection parameters and information. The following URL represents an example of the required parameters for requesting a map. Every map request must include a token (tkn) or UserID (usrid), data source (ds), center point (c), and scale factor (sf). See the Map parameter for details on these required parameters.
http://www.arcwebservices.com/services/v2006/restmap?actn=getMap&usrid=<UserID generated in step 1>&ds=ArcWeb:TA.Streets.NA&c=-117.1817|34.0556&sf=52500

See Sample requests for a variety of URL sample requests you can use to help you create REST maps.

Parameters

The following tables describe the required and optional parameters you can use in your REST URLs.

Required parameters

Authentication and Map are the main parameters for REST mapping URLs and are required.

Authentication (actn=getToken)
Parameter	Description	Valid Values
usr (required)	ArcWeb Services account user name.	String containing valid user name. Case sensitive.
pswd (required)	ArcWeb Services account password.	String containing valid password. Case sensitive.
tout (optional)	Expiration time of token, in minutes.	Minutes to expiration. Default value is 60. Maximum value is 1440.
ip (optional)	IP address of client application viewing ArcWeb maps. Only use if the client machine getting the token is different from the machine requesting the maps. Use the IP utility to view the IP address seen by ArcWeb.	IP address in format xxx.xxx.xx.xxx such as 198.102.62.126.

Authentication (actn=getUserID)
Parameter	Description	Valid Values
usr (required)	ArcWeb Services account user name.	String containing valid user name. Case sensitive.
pswd (required)	ArcWeb Services account password.	String containing valid password. Case sensitive.

Map (actn=getMap)
Parameter	Description	Valid Values
tkn (required if not using usrid)	Authentication token returned from a getToken request	Returned string from getToken request. Average length of string is 72–80 characters. Recommended authentication method.
usrid (required if not using tkn)	Authentication token returned from a getUserID request	Returned string from getUserID request. Average length of string is 50–70 characters. To enable and disable UserIDs, visit the ArcWeb UserID account page. ArcWeb recommends using UserIDs only during phases of development and testing, when they offer more flexibility and convenience. ESRI recommends that you change your account password, which invalidates any existing UserIDs, and switch to using tokens before making an application public.
c (required)	Map center point in x\|y coordinates	The x-coordinate of the center point and the y-coordinate of the center point in geographic coordinates (longitude/latitude), separated by a pipeline (\|), for example, -117.1817\|34.0556. See Samples for details on using the c parameter to pan a map.
sf (required)	Geographical scale of the map	The distance ratio between two geographic locations and those two points represented on the map. The distance measured on the map can be any units, and that multiplied by the scale factor will give the actual distance in the measured units. For example, if the distance between two points on the map is 3 cm, for sf=100000, the geographic distance between the two points is 300,000 cm (3 multiplied by 100,000).
ds (required)	Data source	Valid values are bam (best available map) ArcWeb:AND.Roads.World ArcWeb:TA.Streets.EU ArcWeb:TA.Streets.US ArcWeb:TA.Streets.NA If ds=bam, based on the extent of the map, the best available data source is selected from the valid values above. See Map Image data sources for details about these data sources.
w (optional)	Map image width in pixels	Default value is 400. Maximum width is 8192.
h (optional)	Map image height in pixels	Default value is 400. Maximum height is 8192.
a (optional)	Angle to rotate the map	Default value is 0. Values less than 360 rotate the map through that many degrees. Negative values are rotated in the opposite direction.
fmt (optional)	Map image format	Valid values are: svg, swf, jpg, or png. Default value is swf.
stl (optional)	Style sheet used in the map	Style sheets are specific to a data source (ds). The default style for a data source is nt (Neutral). Other options are ce (Classic European), cs (Cool Steel), gs (Gray Scale), or tg (Tangerine). You can set a style for the following data sources: ArcWeb:AND.Roads.World uses nt, gs, or tg; ArcWeb:TA.Streets.EU uses nt, gs, tg, or ce; ArcWeb:TA.Streets.US uses nt, cs, gs, tg, or ce; and ArcWeb:TA.Streets.NA uses nt, gs, or tg. Use the Map Image Web Service Live Sample to preview style sheets in a map.

Optional parameters

You may use the following optional parameters in a REST mapping URL:

Acetate line	Legend	Graticule
Acetate point	North arrow	Projections
Acetate polygon	Scale bar

Acetate line
Note: You must use all or none of the acetate line parameters.
Parameter	Description	Valid Values
ln	The x1\|y1\|x2\|y2...xn\|yn coordinates of a polyline	A series of x- and y-coordinates of a polyline that are separated by pipelines (\|). To display a polyline, set ln=-117\|34\|-95\|45\|-85\|40, where -117\|34 is start point of the polyline, -95\|45 are the x- and y-coordinates of the connecting segment, and -85\|40 is the end point of the polyline. ln parameters can be used multiple times in a request.
lnw	Width in integers	Values can range from 1 to 10. Default value is 1.
lnc	Line color	Line color in HTML color format (aaRRGGBB). Can be used multiple times in a request. Default is FF000000 (opaque and black). The lnc parameter will be ignored if the lnw parameter is not specified.

Acetate point
Note: You must use the acetate point parameters p and pl.
Parameter	Description	Valid Values
p	Point location in x\|y coordinates.	To display a point, set p=-117.1817\|34.0556, where -117.1817 is the x-coordinate and 34.0556 is the y-coordinate of the center point, separated by a pipeline (\|). Use with the pl and/or pi parameter.
pl	Label for the point. Font format is Verdana, normal, 10 point. Label location is set by the point parameter.	Sets a label value for each point or icon on your map. Use with the p parameter.
pi	Icon to use with the point. Icon location is set by the point parameter.	See REST icons for a list of valid values. For example, to display a red pushpin icon, set pi=pushpin_red.gif. Note that for SVG and SWF images to display, you must add pi to your URL so that it is not the last parameter listed. Use with the p parameter.

Acetate polygon
Note: You must use both or neither of the acetate polygon parameters.
Parameter	Description	Valid Values
plg	The x1\|y1\|x2\|y2...xn\|yn coordinates of a polygon	A series of x- and y-coordinates of vertices in a polygon, separated by pipelines (\|). To display a polygon, set plg=-117\|34\|-120\|45\|-100\|50, where -117\|34 is one vertex, -120\|45 is the second vertex, and -100\|50 is the third vertex.
plc	Polygon color	Polygon color in HTML color format (aaRRGGBB). Can be used multiple times in a request. Default is FF000000 (opaque and black). The plc parameter will be ignored if the plg parameter is not specified.

Graticule
Note: If you do not set g, the graticule will not display on the map.
Parameters	Description	Valid Values
g	The distance in degrees between two adjacent latitudes or two adjacent longitudes on the map	Values can range from 1 to 30 and be numeric. Default value is 5.
gc (optional)	Color of graticule	For example, for gc=aaRRGGBB, insert a hexadecimal number in the place of aaRRGGBB. The aa is optional and represents transparency. Default value is 770000ff (blue).
gw (optional)	Width in pixels of the graticule	Values can range from 1 to 10 and be numeric. Default value is 1.

Legend
Note: If you do not set values, the legend will not display on the map.
Parameter	Description	Valid Values
l	The upper left corner of the legend in pixels, from the top left corner of the map.	The x,y coordinates of the legend, separated by a pipeline (\|). For example, to display the legend 10 pixels from the left side of the map and 5 pixels from the top of the map, set l=10\|5, where 10 is the x-coordinate and 5 is the y-coordinate. Use positive integers.

North arrow
Note: You must use all or none of the north arrow parameters.
Parameter	Description	Valid Values
na	The center point of the north arrow in pixels, whose origin (0,0) is from the lower left corner of the map	The x,y coordinate of the center point, separated by a pipeline (\|). A value of (0,0) will display a partially visible north arrow because the origin of the north arrow object is placed in the lower left corner of the map. To display a fully visible north arrow, use the width (naw) and height (nah) when setting the center point. For example, a value of 20\|30 with a width (naw) of 20 and height (nah) of 30 places the north arrow 10 pixels from the y-axis and 15 from the x-axis.
naw	Width in pixels of the north arrow	To ensure that the north arrow is fully visible, use height (nah) and center point (na) when setting the width. See na Description and Valid Values for more information.
nah	Height in pixels of the north arrow	To ensure that the north arrow is fully visible, use the width (naw) and center point (na) when setting the height. See na Description and Valid Values for more information.
nat	Type of north arrow	Valid values are bk (black), bu (blue), or gr (green). Default value is bk.

See Projections for map projection parameters and information.

Scale bar
Note: You must use all or none of the scale bar parameters.
Parameter	Description	Valid Values
sbx	The lower left corner of the scale bar in pixels, from the bottom left corner of the map	The x,y coordinates of the scale bar, separated by a pipeline (\|). For example, to display the scale bar 10 pixels from the left side of the map and 10 pixels from the bottom of the map, set sbx=10\|10, where 10 is the x-coordinate and 10 is the y-coordinate.
sbw	Width in pixels of the scale bar	Use positive integer.
sbt	Type of scale bar	Valid values are 1 (transparent) or 2 (color). Default value is 1.