FRAMES | NO FRAMES
Getting Started with the ArcGIS Server REST API

Introduction

In order to successfully use the ArcGIS Server REST API, you must understand how to construct a URL and interpret the response. All resources and operations exposed by the REST API are accessible through a hierarchy of endpoints for each GIS service published with ArcGIS Server. This tutorial should help you understand the REST API.

1. Determine the well-known endpoint

When using the REST API, you must know the well-known endpoint, which represents a server catalog.

For ArcGIS Server, the default endpoint is:

http://<host>/<instance>/services/<folder>

Where:

As an example, to get to the root directory of Sample Server 1 on ArcGIS Online services, the URL is:

http://sampleserver1.arcgisonline.com/arcgis/rest/services

2. Navigate using Services Directory

When you type in a URL endpoint in your browser, you will see Services Directory. Each ArcGIS Server comes with a Services Directory, which provides a way for you to navigate through the list of services, folders, and operations on a server.

3. Understand the documentation

The REST API documentation has topics on all resources and operations as well as some introductory and reference topics. The hierarchy of resources and operations listed in the table of contents matches the hierarchy of the API itself. Each topic contains a description, URL parameters and examples, and JSON object response examples and explanations.

4. Create a URL and see the response

When using the REST API, you need to construct URLs. Services Directory can help you generate URLs that include both the reference to a resource and any parameters. A URL with parameters will have the following syntax:

http://<resource-url>?<parameter1=value1>&<parameter2=value2>

Where:

Almost all resources have an f parameter. This parameter determines the output format. For more information, you should review Output Formats.

To retrieve information about a Map Service in a JSON object, you would use a URL similar to the following:

http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Demographics/ESRI_Census_USA/MapServer?f=json

The response is in JSON format and looks similar to the following.

{"serviceDescription":"This service presents various population statistics from Census 2000, including total population, population density, racial counts, and more. The map service presents statistics at the state, county, block group, and block point levels.","mapName":"Layers","description":"This service presents various population statistics from Census 2000, including total population, population density, racial counts, and more. The map service presents statistics at the state, county, block group, and block point levels.\n","copyrightText":"US Bureau of the Census: http://www.census.gov","layers":[{"id":0,"name":"Census Block Points","parentLayerId":-1,"defaultVisibility":true,"subLayerIds":null},{"id":1,"name":"Census Block Group","parentLayerId":-1,"defaultVisibility":true,"subLayerIds":null},{"id":2,"name":"Counties","parentLayerId":-1,"defaultVisibility":true,"subLayerIds":[3,4]},{"id":3,"name":"Coarse Counties","parentLayerId":2,"defaultVisibility":true,"subLayerIds":null},{"id":4,"name":"Detailed Counties","parentLayerId":2,"defaultVisibility":true,"subLayerIds":null},{"id":5,"name":"states","parentLayerId":-1,"defaultVisibility":true,"subLayerIds":null}],"spatialReference":{"wkid":4269},"singleFusedMapCache":false,"initialExtent":{"xmin":-185.337909350544,"ymin":-19.11255617006,"xmax":-59.5254875059344,"ymax":108.400033537315,"spatialReference":{"wkid":4269}},"fullExtent":{"xmin":-185.337909357176,"ymin":15.2049923316373,"xmax":-59.5254874993028,"ymax":74.0824850356176,"spatialReference":{"wkid":4269}},"units":"esriDecimalDegrees","documentInfo":{"Title":"USCensus","Author":"serverxadmin","Comments":"","Subject":"","Category":"","Keywords":""}}

In another example, you can request to export a map. In this case, you would use the a map service export operation. For this operation, you need to include the "bbox" parameter. Some parameters are optional and some are required. These requirements are noted in the documentation. An example URL is:

http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Demographics/ESRI_Census_USA/MapServer/export?bbox=-185.3,-28.8,-59.5,118.1

Exported map

The above URL returns the response in HTML format, and you see an image along with its width, height, extent, and scale. If you want the same information returned in a JSON object, you need to include the f parameter:

http://myserver/arcgis/rest/services/maps/world/MapServer/export?bbox=-197.99999664046,-131.792384313038,197.99999664046,125.388423131397&f=json

The response looks similar to the following:

{"href":"http://sampleserver1.arcgisonline.com/arcgisoutput/_ags_map77043d465f5547f09c5b.png", "width":400,"height":400,"extent":{"xmin":-195.85,"ymin":-28.8,"xmax":-48.95,"ymax":118.1,"spatialReference":{"wkid":4269}}, "scale":154341679.023927}

If you want the JSON object response to be more readable, you can use pjson. This option should only be used for debugging purposes since it takes longer to process the response.

http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Demographics/ESRI_Census_USA/MapServer/export?bbox=-185.3,-28.8,-59.5,118.1&f=pjson

{
  "href" : "http://sampleserver1.arcgisonline.com/arcgisoutput/_ags_mape8e1ca53a24a477380c7c9940e7b073d.png", 
  "width" : 400, 
  "height" : 400, 
  "extent" : {
    "xmin" : -195.85, 
    "ymin" : -28.8, 
    "xmax" : -48.95, 
    "ymax" : 118.1, 
    "spatialReference" : {
      "wkid" : 4269
    }
  }, 
  "scale" : 154341679.023927
}

5. Use Services Directory dialog boxes to generate parameter values in the URL

Services Directory includes dialog boxes for all operations valid with a resource. These dialog boxes allow you to input values for URL parameters for testing purposes. In the response, you will see both the results and an encoded URL.

As an example, take a look at the "find" dialog for a USA service on sampleserver1.

http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StateCityHighway_USA/MapServer/find

When you enter this URL or navigate to this URL in Services Directory, you will see the following dialog:

Find dialog

Each field in the dialog is one of the URL parameters for the find operation. The Find topic contains example values that are valid for each parameter. In the following example, a find operation is made on a states layer in the USA map service. The searchText is "New York". Only layer 1 (states) is searched, and the return geometry is requested. The find results are returned in an HTML format.

URL parameters for find

You should also take a look at the URL that was generated. The values you entered into the dialog box as parameters in the URL.

http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StateCityHighway_USA/MapServer/find?searchText=New+York&contains=true&searchFields=&sr=&layers=1&returnGeometry=true

Many characters in the request must be encoded in the URL. Encoding replaces certain special characters with hexidecimal values. Services Directory (being a brower based application) encodes URLs, but you will need to do your own encoding in your application. The following example shows a URL where many spaces, commas, curly brackets, colons and other characters have been encoded.

http://myserver/arcgis/rest/services/maps/world/MapServer/identify?geometryType=esriGeometryPoint&geometry=%7Bx%3A+-104%2C+y%3A+35.6%7D&sr=&layers=&tolerance=&mapExtent=-104%2C35.6%2C-94.32%2C41&imageDisplay=600%2C400%2C96&returnGeometry=true

Note that unless otherwise stated, the URL examples in the REST API documentation will be shown in their unencoded form for better readability.

6. Understand options for sending long JSON objects in a request

When using the REST API, you will normally use an HTML GET method in a form. When you use GET, the entire request is encoded in the URL. This is the preferred method to use whenever possible. However, in this mode, a URL is limited to as few as 1024 characters depending on the browser. Thus, if you have a long JSON object to include in the request, you will need to use POST.

A second option, when using certain Geometry Service and Geoprocessing Service operations, is to continue to use GET and to specify a URL to the input JSON object contained in a file on a public server.

Syntax: geometries={ "url" : "<URL to file>" }
Example: geometries={ "url" : "http://myserver/mygeometries/afile.txt" }

http://myserver/arcgis/rest/services/Geometry/GeometryServer/project?inSR=4326&outSR=54004&geometries={ "url" : "http://myserver/mygeometries/afile.txt" }

7. Use the REST administration page

The REST API comes with an administration page. You can clear the REST API cache or enable and disable Services Directory. Clearing the cache is something you need to do whenever you add services, remove services, update services, or update to a new version of the REST API. This cache is what you access when you use Services Directory.

You open the administration page using the following URL where "myserver" is your host name:

http://myserver/arcgis/rest/admin

You first will see a place to log in. Use a username and password that is part of the ArcGIS administrators account. After logging in, you can clear the cache or enable/disable Services Explorer. For more information about administration, see REST API Admin.