ArcGIS Urban API

The ArcGIS Urban API is a public GraphQL web service that can be used to interact with ArcGIS Urban data directly.

ArcGIS Urban itself uses the Urban API, and as a public service it allows third party tools such as permitting systems, land value databases, simulation tools, etc. to interact directly with ArcGIS Urban models.

Who This Guide is For

This document is intended for people writing applications, scripts, or GraphQL queries that work with ArcGIS Urban data.

A basic familiarity with ArcGIS Urban, web services, and GraphQL is assumed in this guide, though links to helpful reference materials can be found below.

Useful References

  • ArcGIS Urban: Useful resources and documentation covering all aspects of ArcGIS Urban
  • GraphQL: The official GraphQL website, with tutorials and documentation
  • GraphQL Libraries: A list of helpful GraphQL libraries in a variety of programming languages

API Status and Deprecation Policy

The Urban API is currently in Beta. This means that API-incompatible changes may still be made.

Changes to the Urban API which result in deprecating GraphQL types, fields, filters, etc. may occur from time to time. Such changes are annotated in the GraphQL schema with the @deprecated directive.

The reason field in the deprecation notice includes useful information such as migration recommendations as well as the sunset date for the deprecated item. Deprecations may be removed from the Urban API once the sunset date has been reached. New and sunset deprecations are also noted in Urban API release announcements.

Example:

  
 urbanEvent(urbanDatabaseId: PortalItemId!, globalID: GlobalID!): UrbanEvent
    @deprecated(reason: "Use Plans or Projects. (Sunset: 2021-02-01)")

The Urban API Endpoint

The public Urban API endpoint is located at https://urban-api.arcgis.com/graphql.

This single endpoint URL is used for all Urban API GraphQL queries. GraphQL uses the content of the JSON-encoded query sent as part of the request to determine what will be queried or mutated, so only a single endpoint is required for all Urban API usage.

For example, the following curl command will retrieve a list of the IDs and names of all publicly visible Urban Models:

     
curl \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{ "query": "{ urbanModels { id title } }" }' \
  https://urban-api.arcgis.com/graphql

Raw HTTP requests such as the above may be embedded in applications or scripts, but it is more common, and generally easier, to use one of the available GraphQL Libraries.

You may note that there is no authentication in the above query. Without an authorized account, the Urban API provides access only to public data. To access private data or data associated with an account, organization, or group, an access token must be provided in the URL as a parameter:

     
curl \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{ "query": "{ urbanModels { id title } }" }' \
  https://urban-api.arcgis.com/graphql?token=ZG-5cpTb2aKHB09BI5_gxhYnbE5Hl74RZSC_wIMNik-FUj8RdwJgGLLfNAyKPN_ZQSGnvL9BdfAK0qc6zI26Ak3-F-6SfCPdvMgnCXdUY84nRllgFKvIThUgW9Lm1uFq6M5a6KGzUxVJ0aPYmnEE7VYIuY7o_DuchCJbnH_0DbBmJPzKT2t_MWfvF59KVzn9wTwi4Vxb-l_HsM8nvxfC6WE3SPWq5H3hveEHpQAexLE.

The query will now return all Urban Models that the account associated with the token has access to. Tokens may be generated using ESRI libraries such as the generateToken function from the ArcGIS Rest JS library. Note that tokens have a relatively short lifetime, so a token should be requested before running queries rather than hardcoded into query URLs. You can read more about ArcGIS tokens here.

Using the Graphical Query Interface

Loading the Urban API endpoint in a web browser will load an interactive query interface:

Simply press the 'Play' button to run a query. The data returned by the query, along with any errors, will be displayed in the pane next to the query. This is an excellent way to explore the Urban API and prototype queries.

Also note the Docs and Schema tabs to the right. These are extremely valuable sources of information which load their content directly from the Urban API service.

Opening the Schema tab, for instance, lists the complete set of queries and mutations along with their typed arguments and return values. By clicking on a given entry, one can drill-down into each part of the graph API, making it an excellent way to explore and learn about the Urban API.

While writing queries, an auto-complete menu will list available fields. This can be triggered either by simply typing the first letters of a field's name, or by pressing the auto-complete key shortcut which in most browsers is Ctrl+Space.

The query interface also supports advanced features such as query variables and multiple tabs. Your queries will be automatically saved in local storage so you can visit the query interface later and use previous queries.

To use an authentication token with the live query interface, append &token=MY_LONG_TOKEN_VALUE in the URL bar of the query tab. This needs to be done separately for every tab that is open in the query interface.

Data Model Overview

It is useful to have an idea of the data model that ArcGIS Urban uses to represent Urban Models when using the Urban API, as the Urban API operates on that data model. Urban's getting started documentation describes the main concepts such as Plans and Projects, and these are reflected in the Urban API.

The top-level data concept in Urban is the Urban Model, which has configuration as well as Plans and Projects contained within individual Urban Designs:

Urban Model
Urban Designs
Urban Database
Configuration
Indicators
Plans
Projects

Plans may have multiple scenarios, each of which are stored in a data object called a Branch. The branches in turn have parcels, overlays, and zones associated with them. These three elements may also be user-definable types.

Plans
Branches
Parcels
Overlays
Zones
Building Types
Zone Types
Overlay Types
Space Use Types

Similarly, Projects also have scenarios which are stored in Branches. These scenarios contain point and polygon symbols as well as LOD1 buildings. Projects are also labeled with a user-definable Status Type.

Projects
Status Types
Branches
Point Symbols
Polygon Symbols
LOD1 Buildings

All of these concepts appear in the Urban API and are available for querying, creating, updating, and deletion via the relevant GraphQL nodes.

API Patterns

The Urban API consistently employs patterns in its GraphQL design and data return types that make using it easier and more predictable.

Queries

For each type of data in the Urban data model (e.g. Plans, Projects, Branches, etc.) the following GraphQL nodes can be found in the Urban API:

  • <Data Type>: A query which can be used to fetch an object of that type by its ID
  • <Data Type>s: A query which can be used to fetch several objects of that type by its parent object's ID as well as other filtering options. These nodes support pagination using limit/offset fields.

Mutations

Most Urban data model types can also be mutated via the Urban API. Those that can be support the following pattern for mutations:

  • create<Data Type>: A mutation which takes the ID of its parent object (e.g. the ID of the Plan a scenario Branch belongs to) and a <Data Type>Input which is a collection of all the parameters that are possible to have on such an object (e.g. the owner)
  • update<Data Type>: A mutation which takes the ID of the object to update along with an Update<Data Type>Input which is the update analog of the <Data Type>Input used in updates
  • delete<Data Type>: A mutation which deletes one or more objects of a given type by ID. Any dependent data, such as Zones and Parcels in a Project, must be deleted first.

Note that some types may be created and deleted but not updated (e.g. Urban Designs). This is a technical artifact rather than a design oversight.

Object Types

Each type of data in the Urban data model also has a correspondingly named type in the Urban API which are returned by queries. These types have a top-level attributes field which contains the properties for that object. Additionally, types that have an associated geometry also have a top-level geometry field containing the coordinates and spatial reference for its geometry.

For example, here is the complete definition for a Project object from the Urban API schema:

    
type Project {
  attributes: ProjectAttributes!
  geometry: Polygon
}

The types references in the attributes and geometry fields are defined further in the schema as:

                                         
type SpatialReference {
  wkid: Int
}

type Polygon {
  rings: [[[Float!]!]!]
  spatialReference: SpatialReference
}

type ProjectAttributes {
  GlobalID: GlobalID
  Address: String
  ContextWebsceneItemId: String
  CreationDate: Date
  Creator: String
  CustomID: String
  Description: String
  EditDate: Date
  Editor: String
  EndDate: Date
  EventName: String
  Featured: Boolean
  Households: Float
  HouseholdsAfter: Float
  HouseholdsTarget: Float
  Jobs: Float
  JobsAfter: Float
  JobsTarget: Float
  Locked: Boolean
  OwnerName: String
  PlanningMethod: UrbanEventPlanningMethod
  Population: Float
  PopulationAfter: Float
  PopulationTarget: Float
  PublicFeedbackEnabled: Boolean
  PublicFeedbackEndDate: Date
  StartDate: Date
  Status: String
  Thumbnail: String
  WebpageUrl: String
}

There are two exceptions to this pattern: Urban Models and Urban Designs, to which the other queryable objects belong. Query responses for these two types have all fields in the top-level of the object rather than in an attributes field.

Capitalization Conventions

Query, mutation, and field names follow camelCase, while type names and enums follow TitleCase. Identifiers such as GlobalID are capitalized as "ID", with the exception of those ending with "ItemId" where, for historical reasons, the "d" is in lower-case.

Object IDs

There are three types of ID used to uniquely identify objects in an Urban data set:

  1. GlobalID: A standard UUID4 string. Most objects are identified using a GlobalID.
  2. PortalItemId: A UUID4 string, but with all dashes (-) removed. As the name suggests, these are used for portal items hosted on ArcGIS Online.
  3. CustomID: A free-form, user-provided ID string. This allows users to map values in their Urban data base to external references, such as when Zone Types have a pre-existing defined coding. Objects with a CustomID also have an automatically assigned unique GlobalID.

Introspection

GraphQL has powerful introspection capabilities which can be used with the Urban API. This is how the provided graphical query interface loads the schema, for example.

To discover what queries and mutations are available and what the various data types include, introspection queries are a fantastic tool and the recommended method to fetch this information.

Changing Data Directly in ArcGIS Online

Since Urban data is stored in an ArcGIS backend, it is possible to examine and even change that data using ArcGIS Online and other tools. This is highly discouraged and should only be attempted if you are confident in what you are doing as ArcGIS itself does not know what the Urban data model includes and so will allow breaking changes to be made to Urban data stored there.

For this reason, it is highly recommended that all modifications to Urban data be done via the Urban API, which can provide guarantees around data correctness and consistency.