arcgis-rest-services

REST service wrappers for routing, geocoding, printing, places, geoprocessing, and other server-side operations in ArcGIS Maps SDK for JavaScript

Quality

48%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

High

Do not use without reviewing

Fix and improve this skill with Tessl

tessl review fix ./contexts/4.34/skills/arcgis-rest-services/SKILL.md

ArcGIS REST Services

Use this skill when calling ArcGIS Server REST endpoints through the @arcgis/core/rest/* namespace. Covers routing, geocoding, spatial analysis, geoprocessing, printing, places, and other server-side operations.

Import Pattern

REST service modules follow a consistent pattern: import the service module and its corresponding parameters class from rest/support/.

import * as route from "@arcgis/core/rest/route.js";
import RouteParameters from "@arcgis/core/rest/support/RouteParameters.js";
import FeatureSet from "@arcgis/core/rest/support/FeatureSet.js";

All REST service functions accept a service URL as the first argument and a parameters object as the second:

const result = await serviceName.methodName(serviceUrl, params);

Route

Solve routes between stops with optional barriers and directions.

import * as route from "@arcgis/core/rest/route.js";
import RouteParameters from "@arcgis/core/rest/support/RouteParameters.js";
import FeatureSet from "@arcgis/core/rest/support/FeatureSet.js";
import Stop from "@arcgis/core/rest/support/Stop.js";

const stops = new FeatureSet({
  features: [
    new Graphic({
      geometry: { type: "point", longitude: -117.195, latitude: 34.057 },
      attributes: { Name: "Start" }
    }),
    new Graphic({
      geometry: { type: "point", longitude: -117.918, latitude: 33.812 },
      attributes: { Name: "End" }
    })
  ]
});

const routeParams = new RouteParameters({
  stops: stops,
  outSpatialReference: { wkid: 4326 },
  returnDirections: true,
  returnRoutes: true,
  directionsLanguage: "en"
});

const routeUrl = "https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World";
const result = await route.solve(routeUrl, routeParams);

const routeResult = result.routeResults[0];
const routeGeometry = routeResult.route.geometry;
const directions = routeResult.directions;

// Display directions
directions.features.forEach((feature) => {
  console.log(feature.attributes.text, feature.attributes.length.toFixed(2), "miles");
});

Route with Barriers

const pointBarriers = new FeatureSet({
  features: [
    new Graphic({
      geometry: { type: "point", longitude: -117.5, latitude: 33.9 }
    })
  ]
});

const routeParams = new RouteParameters({
  stops: stops,
  pointBarriers: pointBarriers,
  outSpatialReference: { wkid: 4326 },
  returnDirections: true
});

const result = await route.solve(routeUrl, routeParams);

Closest Facility

Find the nearest facilities to a set of incidents.

import * as closestFacility from "@arcgis/core/rest/closestFacility.js";
import ClosestFacilityParameters from "@arcgis/core/rest/support/ClosestFacilityParameters.js";
import FeatureSet from "@arcgis/core/rest/support/FeatureSet.js";

const facilities = new FeatureSet({
  features: [
    new Graphic({ geometry: { type: "point", longitude: -117.2, latitude: 34.06 } }),
    new Graphic({ geometry: { type: "point", longitude: -117.3, latitude: 34.1 } }),
    new Graphic({ geometry: { type: "point", longitude: -117.15, latitude: 34.0 } })
  ]
});

const incidents = new FeatureSet({
  features: [
    new Graphic({ geometry: { type: "point", longitude: -117.19, latitude: 34.05 } })
  ]
});

const params = new ClosestFacilityParameters({
  facilities: facilities,
  incidents: incidents,
  defaultTargetFacilityCount: 1,
  returnRoutes: true,
  returnDirections: true,
  outSpatialReference: { wkid: 4326 }
});

const cfUrl = "https://route-api.arcgis.com/arcgis/rest/services/World/ClosestFacility/NAServer/ClosestFacility_World";
const result = await closestFacility.solve(cfUrl, params);

const closestRoute = result.routes[0];
console.log("Distance:", closestRoute.attributes.Total_Kilometers, "km");

Service Area

Generate service area polygons around facilities based on travel time or distance.

import * as serviceArea from "@arcgis/core/rest/serviceArea.js";
import ServiceAreaParameters from "@arcgis/core/rest/support/ServiceAreaParameters.js";
import FeatureSet from "@arcgis/core/rest/support/FeatureSet.js";

const facilitiesFeatureSet = new FeatureSet({
  features: [
    new Graphic({
      geometry: { type: "point", longitude: -117.195, latitude: 34.057 }
    })
  ]
});

const params = new ServiceAreaParameters({
  facilities: facilitiesFeatureSet,
  defaultBreaks: [5, 10, 15], // minutes
  travelMode: { name: "Driving" },
  trimOuterPolygon: true,
  outSpatialReference: { wkid: 4326 }
});

const saUrl = "https://route-api.arcgis.com/arcgis/rest/services/World/ServiceAreas/NAServer/ServiceArea_World";
const result = await serviceArea.solve(saUrl, params);

// Each break value produces a polygon
result.serviceAreaPolygons.forEach((polygon) => {
  console.log("Break:", polygon.attributes.FromBreak, "-", polygon.attributes.ToBreak, "min");
  graphicsLayer.add(new Graphic({ geometry: polygon.geometry, symbol: fillSymbol }));
});

Locator (Geocoding)

Address to Location (Geocoding)

import * as locator from "@arcgis/core/rest/locator.js";

const geocodeUrl = "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer";

const results = await locator.addressToLocations(geocodeUrl, {
  address: { SingleLine: "380 New York St, Redlands, CA" },
  outFields: ["Addr_type", "Match_addr", "StAddr", "City"],
  maxLocations: 5
});

results.forEach((result) => {
  console.log(result.address);       // Matched address
  console.log(result.location);      // Point geometry
  console.log(result.score);         // Match score (0-100)
  console.log(result.attributes);    // Returned fields
});

Location to Address (Reverse Geocoding)

import * as locator from "@arcgis/core/rest/locator.js";

const geocodeUrl = "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer";

const result = await locator.locationToAddress(geocodeUrl, {
  location: { type: "point", longitude: -117.195, latitude: 34.057 }
});

console.log(result.address);        // Full address string
console.log(result.attributes);     // Address components

Suggest Locations (Autocomplete)

import * as locator from "@arcgis/core/rest/locator.js";

const geocodeUrl = "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer";

const suggestions = await locator.suggestLocations(geocodeUrl, {
  text: "380 New York",
  location: { type: "point", longitude: -117.195, latitude: 34.057 }
});

suggestions.forEach((suggestion) => {
  console.log(suggestion.text);      // Display text
  console.log(suggestion.magicKey);  // Use with addressToLocations
});

// Use magicKey to get the full result
const results = await locator.addressToLocations(geocodeUrl, {
  address: { SingleLine: suggestions[0].text },
  magicKey: suggestions[0].magicKey,
  outFields: ["*"]
});

Find

Find features in a map service by attribute values.

import * as find from "@arcgis/core/rest/find.js";
import FindParameters from "@arcgis/core/rest/support/FindParameters.js";

const params = new FindParameters({
  searchText: "Los Angeles",
  layerIds: [0, 1, 2],
  searchFields: ["Name", "City"],
  returnGeometry: true,
  outSpatialReference: { wkid: 4326 }
});

const mapServiceUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer";
const result = await find.find(mapServiceUrl, params);

result.results.forEach((findResult) => {
  console.log("Layer:", findResult.layerId);
  console.log("Value:", findResult.value);
  console.log("Feature:", findResult.feature);
});

Identify

Identify features at a specific location on a map service.

import * as identify from "@arcgis/core/rest/identify.js";
import IdentifyParameters from "@arcgis/core/rest/support/IdentifyParameters.js";

const params = new IdentifyParameters({
  geometry: view.toMap(screenPoint),
  mapExtent: view.extent,
  tolerance: 3,
  width: view.width,
  height: view.height,
  layerOption: "all",                // "top", "visible", "all"
  returnGeometry: true,
  spatialReference: view.spatialReference
});

const mapServiceUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer";
const result = await identify.identify(mapServiceUrl, params);

result.results.forEach((identifyResult) => {
  console.log("Layer:", identifyResult.layerName);
  console.log("Feature:", identifyResult.feature);
  console.log("Attributes:", identifyResult.feature.attributes);
});

Print

Export a map to PDF, PNG, or other formats using a server-side print service.

import * as print from "@arcgis/core/rest/print.js";
import PrintTemplate from "@arcgis/core/rest/support/PrintTemplate.js";
import PrintParameters from "@arcgis/core/rest/support/PrintParameters.js";

const template = new PrintTemplate({
  format: "pdf",                             // "pdf", "png32", "png8", "jpg", "gif", "eps", "svg", "svgz"
  layout: "letter-ansi-a-landscape",         // Layout name from print service
  layoutOptions: {
    titleText: "My Map Export",
    authorText: "Map Author",
    scalebarUnit: "Miles"
  },
  exportOptions: {
    dpi: 300,
    width: 800,
    height: 1100
  }
});

const params = new PrintParameters({
  view: view,
  template: template
});

const printUrl = "https://utility.arcgisonline.com/arcgis/rest/services/Utilities/PrintingTools/GPServer/Export%20Web%20Map%20Task";
const result = await print.execute(printUrl, params);

// Open the exported file
window.open(result.url);

Places

Search for points of interest (POI) using the ArcGIS Places service.

Query Places Near a Point

import * as places from "@arcgis/core/rest/places.js";
import PlacesQueryParameters from "@arcgis/core/rest/support/PlacesQueryParameters.js";

const queryParams = new PlacesQueryParameters({
  categoryIds: ["13065"],                    // Restaurants
  radius: 500,                               // meters
  point: { type: "point", longitude: -87.626, latitude: 41.882 },
  pageSize: 20
});

const results = await places.queryPlacesNearPoint(queryParams);

results.results.forEach((place) => {
  console.log(place.name);
  console.log(place.categories[0].label);
  console.log(place.location);
  console.log("Distance:", place.distance, "m");
});

// Pagination - get next page
if (results.nextPage) {
  const nextResults = await results.nextPage();
}

Query Places Within Extent

import * as places from "@arcgis/core/rest/places.js";
import PlacesQueryParameters from "@arcgis/core/rest/support/PlacesQueryParameters.js";

const queryParams = new PlacesQueryParameters({
  categoryIds: ["16000"],                    // Landmarks and Outdoors
  xmin: -87.65,
  ymin: 41.87,
  xmax: -87.60,
  ymax: 41.90
});

const results = await places.queryPlacesWithinExtent(queryParams);

Fetch Place Details

import * as places from "@arcgis/core/rest/places.js";
import FetchPlaceParameters from "@arcgis/core/rest/support/FetchPlaceParameters.js";

const fetchParams = new FetchPlaceParameters({
  placeId: results.results[0].placeId,
  requestedFields: ["all"]                   // or specific: ["name", "address", "contactInfo", "hours"]
});

const details = await places.fetchPlace(fetchParams);
const placeDetails = details.placeDetails;

console.log("Name:", placeDetails.name);
console.log("Address:", placeDetails.address.streetAddress);
console.log("City:", placeDetails.address.locality);
console.log("Phone:", placeDetails.contactInfo?.telephone);
console.log("Website:", placeDetails.contactInfo?.website);
console.log("Hours:", placeDetails.hours?.opening);
console.log("Rating:", placeDetails.rating?.user);

Places Category IDs

Category	ID
Arts and Entertainment	`10000`
Business and Professional Services	`11000`
Community and Government	`12000`
Dining and Drinking	`13000`
Health and Medicine	`15000`
Landmarks and Outdoors	`16000`
Retail	`17000`
Sports and Recreation	`18000`
Travel and Transportation	`19000`

Geoprocessor

Run custom geoprocessing tasks on ArcGIS Server.

Synchronous Execution

import * as geoprocessor from "@arcgis/core/rest/geoprocessor.js";

const gpUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Elevation/ESRI_Elevation_World/GPServer/Viewshed";

const params = {
  Input_Observation_Point: new FeatureSet({ features: [pointGraphic] }),
  Viewshed_Distance: 15000
};

const result = await geoprocessor.execute(gpUrl, params);

const outputFeatures = result.results[0].value;
outputFeatures.features.forEach((feature) => {
  graphicsLayer.add(new Graphic({
    geometry: feature.geometry,
    symbol: fillSymbol
  }));
});

Asynchronous Execution (Long-running tasks)

import * as geoprocessor from "@arcgis/core/rest/geoprocessor.js";

const gpUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/911CallsHotspot/GPServer/911CallsHotspot";

const params = {
  Query: "I911 > 0"
};

// Submit job
const jobInfo = await geoprocessor.submitJob(gpUrl, params);

// Wait for job to complete
const completedJobInfo = await jobInfo.waitForJobCompletion();

console.log("Job status:", completedJobInfo.jobStatus);

// Fetch results
const resultData = await completedJobInfo.fetchResultData("Result_Layer");
const resultMapImage = await completedJobInfo.fetchResultMapImageLayer("Result_Layer");

Monitor Job Progress

const jobInfo = await geoprocessor.submitJob(gpUrl, params);

// Poll for status updates
const completedJobInfo = await jobInfo.waitForJobCompletion({
  interval: 2000,  // Check every 2 seconds
  statusCallback: (info) => {
    console.log("Status:", info.jobStatus);
    console.log("Messages:", info.messages);
  }
});

Geometry Service

Perform server-side geometry operations.

import * as geometryService from "@arcgis/core/rest/geometryService.js";

const geomServiceUrl = "https://utility.arcgisonline.com/ArcGIS/rest/services/Geometry/GeometryServer";

// Project geometries
const projectedGeometries = await geometryService.project(geomServiceUrl, {
  geometries: [point1, point2],
  inSpatialReference: { wkid: 4326 },
  outSpatialReference: { wkid: 3857 }
});

// Buffer geometries
const bufferedGeometries = await geometryService.buffer(geomServiceUrl, {
  geometries: [point],
  distances: [1000],
  unit: "meters",
  outSpatialReference: { wkid: 4326 }
});

// Lengths and areas
const result = await geometryService.areasAndLengths(geomServiceUrl, {
  polygons: [polygon],
  lengthUnit: "meters",
  areaUnit: "square-meters"
});

console.log("Area:", result.areas[0]);
console.log("Perimeter:", result.lengths[0]);

Image Service

Query and identify imagery from an image service.

import * as imageService from "@arcgis/core/rest/imageService.js";
import ImageIdentifyParameters from "@arcgis/core/rest/support/ImageIdentifyParameters.js";

const imageServiceUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/NLCDLandCover2001/ImageServer";

const params = new ImageIdentifyParameters({
  geometry: clickPoint,
  returnGeometry: true,
  returnCatalogItems: true
});

const result = await imageService.identify(imageServiceUrl, params);

console.log("Pixel value:", result.value);
console.log("Catalog items:", result.catalogItems);

Feature Service

Perform operations directly against a feature service endpoint.

Query Features

import * as query from "@arcgis/core/rest/query.js";
import Query from "@arcgis/core/rest/support/Query.js";

const featureServiceUrl = "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/Landscape_Trees/FeatureServer/0";

const queryParams = new Query({
  where: "Height > 50",
  outFields: ["*"],
  returnGeometry: true,
  outSpatialReference: { wkid: 4326 }
});

const result = await query.executeQueryJSON(featureServiceUrl, queryParams);

console.log("Features found:", result.features.length);
result.features.forEach((feature) => {
  console.log(feature.attributes);
});

Apply Edits

import FeatureLayer from "@arcgis/core/layers/FeatureLayer.js";

const featureLayer = new FeatureLayer({
  url: "https://services.arcgis.com/.../FeatureServer/0"
});

// Add features
const addResult = await featureLayer.applyEdits({
  addFeatures: [
    new Graphic({
      geometry: { type: "point", longitude: -117.19, latitude: 34.05 },
      attributes: { Name: "New Feature", Value: 100 }
    })
  ]
});

// Update features
const updateResult = await featureLayer.applyEdits({
  updateFeatures: [
    new Graphic({
      attributes: { ObjectID: 1, Name: "Updated Name" },
      geometry: { type: "point", longitude: -117.2, latitude: 34.06 }
    })
  ]
});

// Delete features
const deleteResult = await featureLayer.applyEdits({
  deleteFeatures: [
    { objectId: 1 },
    { objectId: 2 }
  ]
});

// Check results
addResult.addFeatureResults.forEach((result) => {
  console.log("Added ObjectID:", result.objectId, "Success:", !result.error);
});

Authentication for REST Services

Premium services (routing, geocoding, places) require authentication via API key or OAuth.

API Key

import esriConfig from "@arcgis/core/config.js";

// Set API key globally
esriConfig.apiKey = "YOUR_API_KEY";

// Now all premium REST calls will use this key
const results = await locator.addressToLocations(geocodeUrl, params);

Per-Request Authentication

import esriId from "@arcgis/core/identity/IdentityManager.js";

// Register a token for a specific server
esriId.registerToken({
  server: "https://route-api.arcgis.com",
  token: "YOUR_TOKEN"
});

Migration from Legacy Patterns

Legacy Pattern	Modern Pattern
`require("esri/tasks/RouteTask")`	`import * as route from "@arcgis/core/rest/route.js"`
`new RouteTask({ url })`	`route.solve(url, params)`
`require("esri/tasks/Locator")`	`import * as locator from "@arcgis/core/rest/locator.js"`
`new Locator({ url })`	`locator.addressToLocations(url, params)`
`require("esri/tasks/Geoprocessor")`	`import * as geoprocessor from "@arcgis/core/rest/geoprocessor.js"`
`new Geoprocessor({ url })`	`geoprocessor.submitJob(url, params)`
`require("esri/tasks/PrintTask")`	`import * as print from "@arcgis/core/rest/print.js"`
`new PrintTask({ url })`	`print.execute(url, params)`
`require("esri/tasks/IdentifyTask")`	`import * as identify from "@arcgis/core/rest/identify.js"`
`new IdentifyTask({ url })`	`identify.identify(url, params)`
`require("esri/tasks/FindTask")`	`import * as find from "@arcgis/core/rest/find.js"`
`new FindTask({ url })`	`find.find(url, params)`
`require("esri/tasks/ClosestFacilityTask")`	`import * as closestFacility from "@arcgis/core/rest/closestFacility.js"`
`new ClosestFacilityTask({ url })`	`closestFacility.solve(url, params)`
`require("esri/tasks/ServiceAreaTask")`	`import * as serviceArea from "@arcgis/core/rest/serviceArea.js"`
`new ServiceAreaTask({ url })`	`serviceArea.solve(url, params)`

Reference Samples

route - Route finding between stops
closest-facility - Finding nearest facilities
service-area - Generating service area polygons
search - Geocoding with the Search widget and locator
places - Places service for POI discovery
geoprocessor - Running geoprocessing tasks
print - Server-side map printing

Common Pitfalls

Not providing authentication for premium services: Route, places, and geocoding services require an API key or OAuth token. Set esriConfig.apiKey before making requests.
Using wrong parameter class: Each service has its own parameters class (e.g., RouteParameters for route, ClosestFacilityParameters for closestFacility). Using the wrong class causes silent failures or unexpected results.
Forgetting to set outSpatialReference: Results default to the service's spatial reference. Always set outSpatialReference on parameter objects to match your view's spatial reference:
```
const params = new RouteParameters({
  stops: stops,
  outSpatialReference: view.spatialReference  // Match the view
});
```
Using legacy task pattern instead of modern rest/ imports*: The esri/tasks/* pattern is deprecated. Use @arcgis/core/rest/* modules with static function calls instead of class instantiation.

Not handling service errors: REST service calls can fail due to network issues, insufficient credits, or invalid parameters. Always wrap calls in try/catch:

try {
  const result = await route.solve(routeUrl, routeParams);
} catch (error) {
  if (error.name === "AbortError") {
    console.log("Request was cancelled");
  } else {
    console.error("Service error:", error.message);
  }
}

Repository: SaschaBrunnerCH/arcgis-maps-sdk-js-ai-context
Path: contexts/4.34/skills/arcgis-rest-services/SKILL.md
Commit: d84407b

Last updated: about 15 hours ago
First committed: 5 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.