Service request types

The ArcGIS Geocoding service supports two different types of requests: Direct request or Job request. Each type of request returns exactly the same results the difference is how the request is made and how the results are obtained. The method you use depends on the complexity of your task, the expected processing time and the size of the data involved.

This section provides information about the different types of requests, their capabilities, and when to use them.

Direct requests

A direct request is a single HTTPS request to a service for a transaction that typically has a short duration.

Use a direct request when:

The data and number of parameters you are sending to the service is small in size.
You want results returned in the response from a single operation.
You want results returned quickly, typically under a few seconds.
You do not need to cancel a request or perform periodic status checks.

Example

The general steps to perform a direct request are:

Select the request.
Supply the appropriate parameters.
Make the request. 1.Access the results.

Request

cURL

HTTP

Use dark colors for code blocks

Copy

1
2
3
4
curl https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates \
-d "f=pjson" \
-d "address=1600 Pennsylvania Ave NW, DC" \
-d "token=<ACCESS_TOKEN>"

Run in Postman

Response

Use dark colors for code blocksCopy
{
  "spatialReference": {
    "wkid": 4326,
    "latestWkid": 4326
  },
  "candidates": [
    {
      "address": "1600 Pennsylvania Ave NW, Washington, District of Columbia, 20500",
      "location": {
        "x": -77.036548499999995,
        "y": 38.89767599999999
      },
      "score": 100,
      "attributes": {
        "Loc_name": "World",
        "Status": "M",
        "Score": 100,
        "Match_addr": "1600 Pennsylvania Ave NW, Washington, District of Columbia, 20500",
        "LongLabel": "1600 Pennsylvania Ave NW, Washington, DC, 20500, USA",
        "ShortLabel": "1600 Pennsylvania Ave NW",
        "Addr_type": "PointAddress",
        "Type": "",
        "PlaceName": "",
        "Place_addr": "1600 Pennsylvania Ave NW, Washington, District of Columbia, 20500",
        "Phone": "",
        "URL": "",
        "Rank": 20,
        "AddBldg": "",
        "AddNum": "1600",
        "AddNumFrom": "",
        "AddNumTo": "",
        "AddRange": "",
        "Side": "",
        "StPreDir": "",
        "StPreType": "",
        "StName": "Pennsylvania",
        "StType": "Ave",
        "StDir": "NW",
        "BldgType": "",
        "BldgName": "",
        "LevelType": "",
        "LevelName": "",
        "UnitType": "",
        "UnitName": "",
        "SubAddr": "",
        "StAddr": "1600 Pennsylvania Ave NW",
        "Block": "",
        "Sector": "",
        "Nbrhd": "",
        "District": "",
        "City": "Washington",
        "MetroArea": "",
        "Subregion": "District of Columbia",
        "Region": "District of Columbia",
        "RegionAbbr": "DC",
        "Territory": "",
        "Zone": "",
        "Postal": "20500",
        "PostalExt": "",
        "Country": "USA",
        "LangCode": "ENG",
        "Distance": 0,
        "X": -77.036548499999995,
        "Y": 38.89767599999999,
        "DisplayX": -77.036548499999995,
        "DisplayY": 38.89767599999999,
        "Xmin": -77.0375485,
        "Xmax": -77.03554849999999,
        "Ymin": 38.896675999999992,
        "Ymax": 38.898675999999988,
        "ExInfo": ""
      },
      "extent": {
        "xmin": -77.0375485,
        "ymin": 38.896675999999992,
        "xmax": -77.03554849999999,
        "ymax": 38.898675999999988
      }
    }
  ]
}

Error handling

When performing a direct request, the response object will contain the results of the request if the response is successful. If the request failed, an error object with HTTP status code and optionally extendedCode values will be returned.

Use dark colors for code blocksCopy
{
  "error": {
    "code": 400,
    "extendedCode": -2147024809,
    "message": "Invalid or missing input parameters.",
    "details": ["Layer [Route_(null)] could not be found in the map or is of the wrong type."]
  }
}

In some cases the response will be successful, but partial results may be returned. In these cases the messages array will contain pertinent information regarding the status of the results.

Expand
Use dark colors for code blocksCopy
  "messages": [
    {
      "type": "informative",
      "description": "Some stops could not be reached"
    }
  ]
}

Job requests

A job request is an HTTPS request to a service that starts a server-side operation (or job) with a long duration. A job request returns a job ID that is used by client applications to make subsequent HTTPS requests to determine job status updates and, when it is complete, to download the final job output.

Use a job request when:

Your problem involves significant time to process, such as large scale geoprocessing or complex spatial analysis.
You want to monitor the status of long running transactions and retrieve the results when they are ready.
You have a large long-running task and don't want time outs.
You want to submit multiple jobs simultaneously, allowing for efficient processing of multiple tasks without waiting for one to complete before starting another.

The general steps to perform a job request are:

Make a submitJob request with the appropriate parameters to get a jobId.
Using the jobId, make periodic requests to check until jobStatus returned is esriJobSucceeded | esriJobFailed | esriJobTimedOut.
- To cancel a job you can append /cancel to the request url.
Use the jobId to get one or more results.

Example

Request

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

POST https://geocode-beta.arcgis.com/arcgis/rest/services/World/GeocodeServer/batchGeocode/beta/submitJob HTTP/1.1
content-type: application/x-www-form-urlencoded
User-Agent: {USER_AGENT}

item = {'itemID': '{ITEM_ID}'}
&token={ACCESS_TOKEN}
&fieldMapping=Address:street_address,City:municipality,Region:state,Postal:zip_code
&outFields='*'

Run in Postman

Response

Use dark colors for code blocksCopy
{
  "jobId": "{JOB_ID}",
  "jobStatus": "{esriJobSubmitted | esriJobWaiting | esriJobExecuting | esriJobSucceeded | esriJobFailed | esriJobTimedOut | esriJobCancelling | esriJobCancelled}",
  "messages": []
}

Request

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
POST https://geocode-beta.arcgis.com/arcgis/rest/services/World/GeocodeServer/batchGeocode/beta/jobs/{JOB_ID} HTTP/1.1
content-type: application/x-www-form-urlencoded
User-Agent: {USER AGENT}

&token={ACCESS_TOKEN}

Run in Postman

Response

Use dark colors for code blocksCopy
{
  "jobId": "{JOB_ID}",
  "jobStatus": "{esriJobSubmitted | esriJobSucceeded | esriJobExecuting | esriJobSucceeded}",
  "status": "{SUBMITTED | RUNNABLE | STARTING | RUNNING | SUCCEEDED}",
  "messages": [
    {
      "description": "Total Matched/Tied/Unmatched: 469/26/5",
      "type": "esriJobMessageTypeInformative"
    }
  ],
  "results": {
    "geocodeResult": {
      "paramUrl": "results/geocodeResult"
    }
  }
}

Request

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
POST https://geocode-beta.arcgis.com/arcgis/rest/services/World/GeocodeServer/batchGeocode/beta/jobs/{JOB_ID}/results/geocodeResult HTTP/1.1
content-type: application/x-www-form-urlencoded
User-Agent: {USER AGENT}

token: {ACCESS TOKEN}

Run in Postman

Response

Use dark colors for code blocksCopy
{
  "paramName": "geocodeResult",
  "dataType": "GPDataFile",
  "value": {
    "url": "https://geocode-beta.arcgis.com/rest/services/World/GeocodeServer/batchGeocode/beta/download/{JOB_ID}.zip"
  }
}

Request

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
POST https://geocode-beta.arcgis.com/arcgis/rest/services/World/GeocodeServer/batchGeocode/beta/jobs/{JOB_ID} HTTP/1.1
content-type: application/x-www-form-urlencoded
User-Agent: {USER AGENT}

&token={ACCESS_TOKEN}

Run in Postman

Response

Use dark colors for code blocksCopy
{
  "jobId": "{JOB_ID}",
  "jobStatus": "{esriJobSubmitted | esriJobSucceeded | esriJobExecuting | esriJobSucceeded}",
  "status": "{SUBMITTED | RUNNABLE | STARTING | RUNNING | SUCCEEDED}",
  "messages": [
    {
      "description": "Total Matched/Tied/Unmatched: 469/26/5",
      "type": "esriJobMessageTypeInformative"
    }
  ],
  "results": {
    "geocodeResult": {
      "paramUrl": "results/geocodeResult"
    }
  }
}

Error handling

The workflow for performing a job request is a multi-step process. For each step in the process (Submit job, Check status, Get results) a response object is returned. If there are issues related to accessing the job, an error object will be returned containing an error code and in some cases an additional extendedCode value.

Example error object with HTTP status code:

Use dark colors for code blocksCopy
{
  "error": {
    "code": 499,
    "message": "Token Required",
    "details": []
  }
}

Example error with HTTP status code and extendedCode:

Use dark colors for code blocksCopy
{
  "error": {
    "code": 400,
    "extendedCode": -2147220218,
    "message": "Job not found on server.",
    "details": ["JobId not found : null. "]
  }
}

If the job failed, the jobStatus will be esriJobFailed and the messages array will contain pertinent information regarding the status of the job.

Example response for a failed job:

Use dark colors for code blocksCopy
{
  "jobId": "{JOB_ID}",
  "jobStatus": "esriJobFailed",
  "messages": [
    {
      "type": "esriJobMessageTypeInformative",
      "description": "Submitted."
    },
    {
      "type": "esriJobMessageTypeInformative",
      "description": "Executing..."
    },
    {
      "type": "esriJobMessageTypeWarning",
      "description": "Location \"O2\" in \"Stops\" is unlocated."
    },
    {
      "type": "esriJobMessageTypeWarning",
      "description": "Need at least 2 valid stops."
    },
    {
      "type": "esriJobMessageTypeError",
      "description": "ERROR 030024: Solve returned a failure."
    },
    {
      "type": "esriJobMessageTypeError",
      "description": "\"Stops\" does not contain valid input for any route."
    },
    {
      "type": "esriJobMessageTypeError",
      "description": "Failed to execute (FindRoutes)."
    },
    {
      "type": "esriJobMessageTypeError",
      "description": "Failed."
    }
  ]
}

If the job succeeded, the jobStatus will be esriJobSucceeded, the messages array may still contain pertinent information regarding the status of the job, especially if there are warning messages.

Example response for a successful job with warning messages:

Use dark colors for code blocksCopy
{
  "jobId": "{JOB_ID}",
  "jobStatus": "esriJobSucceeded",
  "results": {
    "Solve_Succeeded": {
      "paramUrl": "results/Solve_Succeeded"
    },
    "Output_Routes": {
      "paramUrl": "results/Output_Routes"
    },
    "Output_Route_Edges": {
      "paramUrl": "results/Output_Route_Edges"
    },
    "Output_Directions": {
      "paramUrl": "results/Output_Directions"
    },
    "Output_Stops": {
      "paramUrl": "results/Output_Stops"
    },
    "Output_Network_Analysis_Layer": {
      "paramUrl": "results/Output_Network_Analysis_Layer"
    },
    "Output_Route_Data": {
      "paramUrl": "results/Output_Route_Data"
    },
    "Output_Result_File": {
      "paramUrl": "results/Output_Result_File"
    },
    "Output_Network_Analysis_Layer_Package": {
      "paramUrl": "results/Output_Network_Analysis_Layer_Package"
    },
    "Output_Direction_Points": {
      "paramUrl": "results/Output_Direction_Points"
    },
    "Output_Direction_Lines": {
      "paramUrl": "results/Output_Direction_Lines"
    },
    "Usage_Cost": {
      "paramUrl": "results/Usage_Cost"
    }
  },
  "inputs": {
    "Stops": {
      "paramUrl": "inputs/Stops"
    },
    "Measurement_Units": {
      "paramUrl": "inputs/Measurement_Units"
    },
    "Reorder_Stops_to_Find_Optimal_Routes": {
      "paramUrl": "inputs/Reorder_Stops_to_Find_Optimal_Routes"
    },
    "Preserve_Terminal_Stops": {
      "paramUrl": "inputs/Preserve_Terminal_Stops"
    },
    "Return_to_Start": {
      "paramUrl": "inputs/Return_to_Start"
    },
    "Use_Time_Windows": {
      "paramUrl": "inputs/Use_Time_Windows"
    },
    "Time_Zone_for_Time_of_Day": {
      "paramUrl": "inputs/Time_Zone_for_Time_of_Day"
    },
    "UTurn_at_Junctions": {
      "paramUrl": "inputs/UTurn_at_Junctions"
    },
    "Point_Barriers": {
      "paramUrl": "inputs/Point_Barriers"
    },
    "Line_Barriers": {
      "paramUrl": "inputs/Line_Barriers"
    },
    "Polygon_Barriers": {
      "paramUrl": "inputs/Polygon_Barriers"
    },
    "Use_Hierarchy": {
      "paramUrl": "inputs/Use_Hierarchy"
    },
    "Restrictions": {
      "paramUrl": "inputs/Restrictions"
    },
    "Attribute_Parameter_Values": {
      "paramUrl": "inputs/Attribute_Parameter_Values"
    },
    "Route_Shape": {
      "paramUrl": "inputs/Route_Shape"
    },
    "Route_Line_Simplification_Tolerance": {
      "paramUrl": "inputs/Route_Line_Simplification_Tolerance"
    },
    "Populate_Route_Edges": {
      "paramUrl": "inputs/Populate_Route_Edges"
    },
    "Populate_Directions": {
      "paramUrl": "inputs/Populate_Directions"
    },
    "Directions_Language": {
      "paramUrl": "inputs/Directions_Language"
    },
    "Directions_Distance_Units": {
      "paramUrl": "inputs/Directions_Distance_Units"
    },
    "Directions_Style_Name": {
      "paramUrl": "inputs/Directions_Style_Name"
    },
    "Travel_Mode": {
      "paramUrl": "inputs/Travel_Mode"
    },
    "Impedance": {
      "paramUrl": "inputs/Impedance"
    },
    "Time_Zone_for_Time_Windows": {
      "paramUrl": "inputs/Time_Zone_for_Time_Windows"
    },
    "Save_Output_Network_Analysis_Layer": {
      "paramUrl": "inputs/Save_Output_Network_Analysis_Layer"
    },
    "Save_Route_Data": {
      "paramUrl": "inputs/Save_Route_Data"
    },
    "Time_Impedance": {
      "paramUrl": "inputs/Time_Impedance"
    },
    "Distance_Impedance": {
      "paramUrl": "inputs/Distance_Impedance"
    },
    "Output_Format": {
      "paramUrl": "inputs/Output_Format"
    },
    "Ignore_Invalid_Locations": {
      "paramUrl": "inputs/Ignore_Invalid_Locations"
    },
    "Locate_Settings": {
      "paramUrl": "inputs/Locate_Settings"
    }
  },
  "messages": [
    {
      "type": "esriJobMessageTypeWarning",
      "description": "Location \"O3\" in \"Stops\" is unlocated."
    },
    {
      "type": "esriJobMessageTypeWarning",
      "description": "WARNING 030025: Partial solution generated."
    }
  ]
}

HTTP Operations

Most ArcGIS Services support making requests as either a GET or POST. Below is a table describing the key differences between each:

Feature	`GET`	`POST`
Purpose	Retrieve data from a server, peform search queries	Send data to a server or update server state such as Form submissions, file uploads, and data updates
Data	Visible in URL parameters	Sent in request body
Security	Less secure, data visible in URL. Parameters remain in browser history	More secure, data not visible in URL. Parameters are not saved in browser history
Caching	Can be cached	Not typically cached
Bookmarking	Can be bookmarked	Cannot be bookmarked
Data length	Limited by URL length (typically 2048 characters)	No restrictions
Data types	Only supports `string` data	Support various data type (string, numeric, binary)
Encoding	`application/x-www-form-urlencoded`	`application/x-www-form-urlencoded` or `multipart/form-data`