API patterns

The Urban API consistently uses patterns in its GraphQL design and data return types, making it easier and more predictable to use.

Object types

Each data type in the Urban data model has a correspondingly named type in the Urban API. All types have a top-level attributes field that contains the properties of the object. In addition, types that have an associated geometry also have a top-level geometry field containing coordinates and a spatial reference for their geometry.

For example, here is the complete definition of a project from the Urban API schema:

      
1
2
3
4
5
6
type Project {
  attributes: ProjectAttributes!
  geometry: Polygon
  branches: [ProjectBranch]!
  statusType: StatusType
}

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

                             
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
type SpatialReference {
  wkid: Int!
}

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

type ProjectAttributes {
  GlobalID: GlobalID!
  Address: String
  ContextWebsceneItemId: PortalItemId
  CustomID: String
  Description: String
  EndDate: Timestamp!
  EventName: String!
  Featured: Boolean!
  Locked: Boolean!
  MetricsDashboardCharts: [MetricsDashboardChart!]!
  OwnerName: String!
  PlanningMethod: UrbanEventPlanningMethod
  PublicFeedbackEnabled: Boolean!
  PublicFeedbackEndDate: Timestamp
  StartDate: Timestamp!
  Status: GlobalID
  Thumbnail: String
  WebpageUrl: String
}

Object IDs

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

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

Queries

There are the following GraphQL nodes for querying data:

  • <Data Type>: A query used to fetch a single object of that type by its ID, for example, urban model or urban design database.
  • <Data Type>s: A query used to fetch several objects of that type, for example, plans, projects, or branches. These nodes support filtering as well as pagination using limit/offset.

These queries can be nested within each other, for example:

               
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
query {
  urbanDesignDatabase(urbanDesignDatabaseId: "URBAN_DESIGN_DATABASE_ID") {
    title
    plans(paging: { limit: 5 }) {
      attributes {
        EventName
      }
      branches {
        attributes {
          BranchName
        }
      }
    }
  }
}

Mutations

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

  • create<Data Type>s: A mutation that takes the urban database ID and a list of Create<Data Type>Input which contains all the parameters that are possible to have on such an object.
  • update<Data Type>s: A mutation that takes the urban database ID and a list of Update<Data Type>Input which is the update analog of the Create<Data Type>Input used in creates.
  • delete<Data Type>s: A mutation that 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.

Urban database IDs

Each urban model consists of two databases: a writable urban database and a read-only database view. For more information, see ArcGIS Urban documentation. These databases have different identifiers. Both IDs are exposed via the API but serve different purposes depending on the database access settings:

  • The urban database provides write access. Therefore, urbanDatabaseId is used to modify (create, update, or delete) data through mutations.
  • The urban database view provides read-only access. Therefore, urbanDatabaseViewId is used to read from the database through queries.

Capitalization conventions

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

Handling units

Urban API expects input in metric units for all numeric object properties that have a specified unit. Convert imperial units to the metric system before passing them to the Urban API. For more information on the individual units set for different properties, check the API documentation available in the Playground or via GraphQL introspection queries.

Handling spatial reference

A spatial reference provides information about the coordinate system of geographic data, such as a map, layer, or geometry.

Coordinate systems are used to locate geographic features on a map or within a scene. The location of each feature is defined with coordinates, expressed relative to the given coordinate system.

Coordinate systems can be divided into different categories, including:

  • Geographic Coordinate Systems (GCS), which use a three-dimensional spherical or ellipsoidal surface to define location on Earth. Example: WGS84 spatial reference.
  • Projected Coordinate Systems (PCS), which are two-dimensional Cartesian coordinate systems projected on a flat surface. Example: WGS84 Web Mercator spatial reference.

See ArcGIS developers documentation to learn more about spatial references.

Defining the spatial reference

To identify a specific coordinate system, you can use:

  • Well-Known ID (WKID) - an ID identifying a coordinate system
  • Well-Known Text (WKT) - a textual definition of the coordinate system

The Urban API uses WKIDs to determine a spatial reference assigned to geometry data.

Spatial reference in ArcGIS Urban

ArcGIS Urban uses the spatial reference WGS 84 Web Mercator (WKID 3857 or 102100). It is the de facto standard for Web mapping applications.

Depending on the type of operation you are using, the spatial reference options vary:

  • When you mutate the data, you can specify any coordinate system of the input geometries. The Urban API will automatically project the input data to WGS 84 Web Mercator.

    As an example, use the following operation to create a new project with geometry in a local spatial reference: NAD 1983 StatePlane Oklahoma North FIPS 3501 Feet (ESRI:102724):

                             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    mutation {
      createProjects(
        urbanDatabaseId: "URBAN_DESIGN_DATABASE_ID"
        projects: [
          {
            attributes: { EndDate: 1659265775610, StartDate: 1626779375610, EventName: "EVENT_NAME", OwnerName: "OWNER_NAME" }
            geometry: {
              spatialReference: { wkid: 102724 }
              rings: [
                [
                  [2111699.7302856445, 242847.81970214844]
                  [2111699.6701049805, 242853.30987548828]
                  [2111720.7598876953, 242853.5601196289]
                  [2111699.7302856445, 242847.81970214844]
                ]
              ]
            }
          }
        ]
      ) {
        attributes {
          GlobalID
        }
      }
    }
  • When you query the data, Urban API will return the geometry in WGS 84 Web Mercator. You cannot request data with a different spatial reference.

    As an example, query the geometry of the project you just created to see that the geometries were successfully transformed and are returned with WKID:3857.

                
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    query {
      urbanDesignDatabase(urbanDesignDatabaseId: "URBAN_DESIGN_DATABASE_ID") {
        projects {
          geometry {
            rings
            spatialReference {
              wkid
            }
          }
        }
      }
    }

    The data returned by the server should look like this:

                           
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    {
      "data": {
        "urbanDesignDatabase": {
          "projects": [
            {
              "geometry": {
                "rings": [
                  [
                    [-10855646.4480598, 4254782.31608666],
                    [-10855646.4603964, 4254784.38277712],
                    [-10855638.5565976, 4254784.43755208],
                    [-10855646.4480598, 4254782.31608666]
                  ]
                ],
                "spatialReference": {
                  "wkid": 102100
                }
              }
            }
          ]
        }
      }
    }
    

Extent

The geographic extent (or a bounding box) allows you to search for an item by location. The extent of an existing urban model or an urban design database can be set when creating the object using the Urban API or in the portal item settings in ArcGIS Online.

Contrary to regular geometry data, the spatial reference of the extent is not customizable and is always provided using coordinates in WGS84 (wkid: 4326). The extent is specified as the minimum and maximum longitude (X) and latitude (Y) of a bounding box.

The Urban API provides the user with an extent argument for the urbanModels and urbanDesignDatabases types. For example, you can search for urban models within the specified bounding box using the following query:

           
1
2
3
4
5
6
7
8
9
10
11
query {
  urbanModels(
    extent: [
      [-105.12199999992012, 39.522999999969905]
      [-104.95599999992025, 39.626999999969804]
    ]
  ) {
    id
    title
  }
}

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