Data model overview
The Urban API operates on the same data model as ArcGIS Urban. For more information on the Urban data model, see Urban documentation. In the Urban API, you can explore the data model by examining the structure of queries. You can also explore the Urban API data model using the Docs tab in GraphiQL in the API reference section.
The Urban API has two main top-level concepts: the urban model and the urban design database.
The elements in the graph can be explained as following:
| Object | Description |
|---|---|
| Urban model | It represents an urban model. It is stored in the ArcGIS portal as a portal item of the object type Urban Model. It allows setting access rights to the urban model. |
| Urban database | Urban database of the urban model. It contains the actual model data: existing conditions for parcels, zoning, land use and overlays as well as public projects. It is stored in the ArcGIS portal as a feature service. It has editing rights, users with proper permissions can write to the urban database. |
| Urban database view* | Read-only synchronized copy of the urban database. All changes to the urban database appear in the urban database view. |
| Config | Configuration of the urban model used for general settings management. |
| Upgrade info | Information on the upgrade status of the urban model. |
| Urban design database | It represents an internal design that planners are working on, that is not yet intended for public display. It is a container for an urban plan or project. It is stored in the ArcGIS portal as a feature service. It allows setting access rights to the urban design database. |
The urban database and urban design database contain the following objects:
The elements in the graphs can be explained as following:
| Object | Description |
|---|---|
| Plan | Long-term urban planning on a large scale. |
| Project | Short-term urban planning at the parcel level. |
| Indicator | Indicator data that provides additional insights about your urban model. |
Plans
The elements in the graph can be explained as following:
| Object | Description |
|---|---|
| Building types | Building types in the plan. A building type defines the mix of spaces used in a building. |
| Overlay types | Overlay types in the plan. An overlay type defines a unique set of conditions in the defined area and interacts with the underlying zoning. |
| Space-use types | Space-use types in the plan. A space-use type describes a purpose for which a space, typically a floor or a part within a building, is being used. |
| Zone types | Zone types in the plan. A zone type describes a certain combination of zoning code restrictions. |
| Branches | Scenarios in the plan. |
| Metric sources | List of sources used for metrics calculation. |
| Metric values | Values stored for metrics. |
| Metrics | Metrics configured for the plan. A metric defines how a numeric value is calculated for a scenario. Each metrics consists of at least one metric source. |
| Overlays | Overlays in the branch of the plan. |
| Parcels | Parcels in the branch of the plan. |
| Spaces | Spaces (floors of future buildings) in the branch of the plan. |
| Zones | Zones in the branch of the plan. |
Projects
| Object | Description |
|---|---|
| Status types | Project status type, describing the current stage of an urban project. |
| Branches | Scenarios in the project. |
| LOD1 buildings | Low level of detail (LOD1) schematic buildings in the branch of the project. |
| Point symbols | Point symbols representing trees, vehicles, and other urban furniture in the branch of the project. |
| Polygon symbols | Polygon symbols representing grass, concrete, water, or other surface layers in the branch of the project. |
Data model changes
The Urban data model and the Urban API may change over time when new features are being introduced. You might need to upgrade your urban models and urban design databases to support these changes.
Checking the upgrade status
Use the following queries to check the upgrade status of the urban model or urban design database:
query {
urbanModel(urbanModelId: "URBAN_MODEL_ID") {
upgradeInfo {
upgradeStatus
message
}
}
}query {
urbanDesignDatabase(urbanDesignDatabaseId: "URBAN_DESIGN_DATABASE_ID") {
upgradeInfo {
upgradeStatus
message
}
}
}The upgrade field will return one of the following results:
Ready: Your urban model or urban design database is up to date and ready to be used.Upgrade: Your urban model or urban design database is outdated and can be upgraded. Some of your queries might not work and throw an error until the upgrade is performed.Available Service: The upgrade status cannot be determined due to the servers being overloaded. Please try again later.Unavailable Invalid: Your urban model or urban design database is invalid and cannot be upgraded. Please contact support.
Depending on the upgrade the message field will return additional information. For example, in the Invalid case you might get additional information why your urban database is invalid.
Upgrading an urban model or urban design database
Use the following queries to upgrade the urban model or urban design database:
mutation {
upgradeUrbanModel(urbanModelId: "URBAN_MODEL_ID") {
upgradeInfo {
upgradeStatus
message
}
}
}mutation {
upgradeUrbanDesignDatabase(urbanDesignDatabaseId: "URBAN_DESIGN_DATABASE_ID") {
upgradeInfo {
upgradeStatus
message
}
}
}The upgrade field will return one of the following results:
Ready: The upgrade was successful and the urban model or urban design database is ready to be used.Service: The upgrade failed due to the servers being overloaded. Please try again later.Unavailable Invalid: Your urban model or urban design database is invalid and cannot be upgraded. Please contact support.