Basic information

API Status

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

Features get added to the Urban API progressively. New releases occur almost every first Wednesday of the month. You can find out about the latest updates, changes, and fixes in the release notes.

Deprecation policy

Deprecated GraphQL types or fields are annotated in the GraphQL schema with the @deprecated directive, as in the following example:

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

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.

Urban API endpoint

The public Urban API endpoint is located at https://urban-api.arcgis.com/graphql. Only this single endpoint URL is required for all Urban API GraphQL operations.

You can access the API using a curl command. Use the following command to retrieve a list of the IDs and names of all publicly visible urban models:

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

Raw HTTP requests may be embedded in applications or scripts, but it is more common and generally easier to use the Playground or programming languages. Learn more about this in the Get started section.

User authentication

Without an authorized ArcGIS Online account you can only access the public data through the Urban API. To access private data that is associated with an account, organization, or group, provide an access token in the URL as a parameter:

https://urban-api.arcgis.com/graphql?token=$TOKEN_VALUE

You can generate a token using ESRI libraries such as the generateToken function from the ArcGIS Rest JS library. Read more about the ArcGIS tokens.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.