Skip To Content
ArcGIS Developers
Dashboard

Get started

To successfully use the ArcGIS REST API, you must understand how to construct a URL and interpret the response. All resources and operations exposed by the ArcGIS Services portion of the REST API are accessible through a hierarchy of endpoints for each GIS service published with ArcGIS Server. A representation of this hierarchy can be observed in the Resource Hierarchy portion of this reference guide.

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 as follows:

https://<host>/<context>/rest/services/<folder>/<serviceName>/<serviceType>/<serviceLayer>/<operation>

Where:

  • host is the ArcGIS Server or web adaptor host name, domain, and top-level domain (.com).

    Example

    https://myOrg.esri.com
  • context is either the site name (arcgis) if you do not have an ArcGIS Web Adaptor associated with your ArcGIS Server deployment, or the web adaptor name for your ArcGIS Server.

    Example for site context

    https://myOrg.esri.com/arcgis

    Example for web adaptor context

    https://myOrg.esri.com/server
  • rest/services indicates the REST services endpoint. You'll see a list of all services in the root directory along with any folders. This part of the URL is case sensitive and should be specified in all lowercase.

    Example

    https://myOrg.esri.com/server/rest/services
  • folder lists all services included in this folder. Folder names are case sensitive and should be specified in the case in which it was created.

    Example

    https://myOrg.esri.com/server/rest/services/Hosted
  • /<serviceName>/<serviceType> represents the name of the service and its type (for example, PopulationDensity/MapServer). The service name is case sensitive and should be specified in the case in which it was created. The service type should always be specified in a mixed case format as defined for each service in the REST API reference (for example, MapServer, GeocodeServer, and GPServer).

    Example

    https://myOrg.esri.com/server/rest/services/Hosted/PopulationDensity/MapServer
  • serviceLayer represents the name of the service layer.

    Example

    https://myOrg.esri.com/server/rest/services/Hosted/PopulationDensity/MapServer/0
  • operation represents the name of a service operation that is actionable for the service layer.

    Example

    https://myOrg.esri.com/arcgis/rest/services/Hosted/PopulationDensity/MapServer/0/query

Browse using the Services Directory

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

Note:

If you're unfamiliar with the Services Directory, see the Using the Services Directory.

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:

Each topic contains a description, URL parameters and examples, and JSON object response examples and explanations.

Create a URL and see the response

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

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

Where:

  • https://<resource-url> is the URL to a given resource. If the resource is a server object extension or a geoprocessing service task, the resource name is case sensitive.
  • <Operation> represents the name of an operation supported on a resource. The operation name is not case sensitive, but it's recommended that you use the operation name as specified in the REST API.
  • ? denotes the beginning of a parameter list.
  • parameter1=value1 is a name-value pair. The parameter values are case sensitive if the value is JSON or enumeration.

Almost all resources have an f parameter. This parameter determines the output format. For more information, see Output formats.

URL and response examples

The following examples demonstrates various ways to construct a request URL and retrieve JSON and pjson responses.

Example one

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

https://myOrg.esri.com/server/rest/services/Demographics/ESRI_Census_USA/MapServer?f=json

The JSON response 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: https://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":""}}

If you want the JSON object response to be more readable, you can use pjson.

{
  "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: https://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": ""
  }
}

Example two

You can request to export a map. In this case, you would use the 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 as follows:

https://myOrg.esri.com/server/rest/services/Demographics/ESRI_Census_USA/MapServer/export?bbox=-185.3,-28.8,-59.5,118.1

Export 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:

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

The JSON response looks similar to the following:

{"href":"https://myOrg.domain.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 the value for the f parameter:

https://myOrg.domain.com/server/rest/services/Demographics/ESRI_Census_USA/MapServer/export?bbox=-185.3,-28.8,-59.5,118.1 &f=pjson

The pjson response would like similar to the following:

{
  "href": "https://myOrg.domain.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
}

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

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

As an example, view the find dialog box for a USA service:

Find operation

Each field in the dialog box 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 search text is New York. Only layer 1 (states) is searched, and the return geometry is requested. The find results are returned in HTML format.

Find operation results

Notice the URL that was generated. The values you entered in the dialog box are shown as parameters in the URL.

https://myOrg.esri.com/server/rest/services/Specialty/ESRI_StateCityHighway_USA/MapServer/find?searchText=New+York&contains=true&searchFields=&sr=&layers=1&layerdefs=&returnGeometry=true&maxAllowableOffset=&f=HTML

Many characters in the request must be encoded in the URL. Encoding replaces certain special characters with hexadecimal values. The Services Directory (being a browser-based application) encodes URLs, but you 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:

https://myOrg.esri.com/server/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 are shown in their unencoded form for better readability.

Understand options for sending long JSON objects in a request

When using the REST API, you'll 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. Consequently, if you have a long JSON object to include in the request, you'll need to use POST.

Note:

Users not directly interacting with our administrative or REST APIs (for example, using scripts or having a web application firewall configured) may encounter query limitations. In instances where a query string exceeds 2048 characters in length, the query should be submitted as a POST request.

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 example

geometries={"url": "<URL to file>"}

Formatting example

geometries={"url": "https://myserver/mygeometries/afile.txt"}

URL example

https://myOrg.domain.com/server/rest/services/Geometry/GeometryServer/project?inSR=4326&outSR=54004&geometries={"url": "https://myserver/mygeometries/afile.txt"}

When making a POST request to an operation that involves uploading a file, such as addAttachment for feature services, specify the content type as multipart/form-data. For all other POST requests, specify the content type as application/x-www-form-urlencoded.