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 last 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:

Use dark colors for code blocks
  
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:

Use dark colors for code blocks
     
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 public data through the Urban API. Use an access token to access private data associated with an account, organization, or group.

Authenticate the user by adding the access token to the request's authorization header: Authorization: Bearer ACCESS_TOKEN. Depending on the way in which you communicate with the server, do one of the following:

  • Add the header to the cURL command like in the example below:

    Use dark colors for code blocks
          
    1
    2
    3
    4
    5
    6
    curl \
      -X POST \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ACCESS_TOKEN" \
      --data '{ "query": "{ urbanModels { id title } }" }' \
      https://urban-api.arcgis.com/graphql
    
  • Add the following content to the HTTP Headers tab when using the GraphQL Playground:

    {"Authorization": "Bearer ACCESS_TOKEN"}.

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.