request | API Reference | ArcGIS Maps SDK for JavaScript 4.31

See also

Example

// request GeoJson data from USGS remote server
let url = "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson";

esriRequest(url, {
  responseType: "json"
}).then((response) => {
  // The requested data
  let geoJson = response.data;
});

Method Overview

Name	Return Type	Summary	Function
	Promise<RequestResponse>	Retrieves data from a remote server or uploads a file from a user's computer.	request

Method Details

esriRequest Method esriRequest(url, options){Promise<RequestResponse>}

Retrieves data from a remote server or uploads a file from a user's computer. If the request returns an Error, the error object will include the details specified in EsriErrorDetails.

Parameters

url String|URL

The request URL.

options RequestOptions

optional

The options specified by the user in the data request. See RequestOptions for available properties.

Returns

Type	Description
Promise<RequestResponse>	Returns a promise that resolves to an object with the RequestResponse specification. If the request returns an Error, the error object will include the details specified in EsriErrorDetails.

Type Definitions

EsriErrorDetails Type Definition EsriErrorDetails

The specification of the details object returned in an Error object.

Properties: getHeader getHeader

A function to retrieve headers sent from the server.

getAllHeaders getAllHeaders

A function for retrieving all headers sent from the server.

httpStatus Number

The status code of the http response.

messageCode String

The error message code.

messages String []

Additional error message(s).

raw Object|String

The raw error object if the server returned a JSON error, or the response text otherwise.

requestOptions RequestOptions

The options used in the http request.

ssl Boolean

Indicates if the request required https.

subCode Number

The error message subcode.

url String

The URL of the request that returned an error message.

RequestOptions Type Definition RequestOptions

An object with the following properties that describe the request.

Properties: authMode String

optional
Default Value:auto

Indicates if and how requests to ArcGIS Services are authenticated. Only applicable when esriConfig.request.useIdentity = true.

Known Value Description

auto The user will be signed in when a secure resource is requested.

anonymous An error will be returned when a secure resource is requested.

immediate The user will be signed in before the resource is requested.

no-prompt Checks for whether the user is already signed in. If so, no additional prompts display for sign-in.

Possible Values:"auto"|"anonymous"|"immediate"|"no-prompt"

body FormData|HTMLFormElement|String

optional
If uploading a file, specify the form data or element used to submit the file here. If specified, the parameters of the query will be added to the URL.

cacheBust Boolean

optional
Default Value:false

If true, the browser will send a request to the server instead of using the browser's local cache. If false, the browser's default cache handling will be used.

headers Object

optional
Headers to use for the request. This is an object whose property names are header names.

method String

optional
Default Value:auto

Indicates if the request should be made using the HTTP DELETE, HEAD, POST, or PUT method. By default, HTTP POST will be used for auto if the request size is longer than the maxUrlLength property set in config.request.

Possible Values:"auto"|"delete"|"head"|"post"|"put"

query Object|URLSearchParams

optional
Default Value:null

Query parameters for the request. The query parameters will be added to the URL if a GET request is used, or if the body property is set. If the body property is not set, the query parameters will be added to the request body when a DELETE, POST, or PUT request is used.

responseType String

optional
Default Value:json

Response format.

Possible Values:"json"|"text"|"array-buffer"|"blob"|"image"|"native"|"document"|"xml"

signal AbortSignal

optional
AbortSignal allows for cancelable requests. If canceled, the promise will be rejected with an error named AbortError. See also AbortController.

Example:

const controller = new AbortController(); const signal = controller.signal; esriRequest(url, { signal }) .then((response) => { // The request went OK }) .catch((err) => { if (err.name === 'AbortError') { console.log('Request aborted'); } else { console.error('Error encountered', err); } }); // Abort requests that are aware of the controller's signal controller.abort();

timeout Number

optional
Default Value:62000

Indicates the amount of time in milliseconds to wait for a response from the server. Set to 0 to wait for the response indefinitely.

useProxy Boolean

optional
Default Value:false

Indicates the request should use the proxy. By default, this is determined automatically based on the domain of the request URL.

withCredentials Boolean

optional
Default Value:false

Indicates if cross-site Access-Control requests should use credentials. It is also possible to push the domain to the config trustedServers if an application requires credentials. For additional information on withCredentials, please refer to this documentation.

RequestResponse Type Definition RequestResponse

Returns a promise that resolves to an object with the following specification. If the request returns an Error, the error object will include the details specified in EsriErrorDetails.

Properties: data *

optional
The requested data. Should match the responseType with the data return type. Possible types are: json, text, array-buffer, blob, image, native, document, and xml.

getHeader getHeader

optional
Method for getting a header sent from the server.

getAllHeaders getAllHeaders

optional
Method for getting all headers sent from the server.

httpStatus Number

optional
Since 4.26 The status code of the http response.

requestOptions RequestOptions

optional
The options specified by the user in the data request. See RequestOptions for available properties.

ssl Boolean

optional
Indicates if the request required https.

url String

optional
The URL used to request the data.

Example

// request GeoJson data from USGS remote server
let url = "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson";

esriRequest(url, {
  responseType: "json"
}).then((response) => {
  // The requested data
  let geoJson = response.data;
});

getAllHeaders Type Definition getAllHeaders(){String[][]}

A function to retrieve all headers sent from the server. CORS only allows a few response headers to be read by default, see: Access-Control-Expose-Headers.

Returns

Type	Description
String [][]	An array of all headers returned from the server. Each header is an array containing the header name and its corresponding value.

Example

esriRequest(url, options)
  .then((response) => {
    console.log("All request headers: ", response.getAllHeaders());
  });

getHeader Type Definition getHeader(headerName){String}

A function to retrieve headers sent from the server. CORS only allows a few response headers to be read by default, see: Access-Control-Expose-Headers.

Parameter

headerName String

The name of the header.

Returns

Type	Description
String	The header value.

Example

esriRequest(url, options)
  .then((response) => {
    // prints the content type of the request: 'application/json'
    console.log("header: ", response.getHeader('Content-Type'));
  });