Data model

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.

Query
Urban model
Urban design database
Urban database
Config
Upgrade info
Top-level concepts in the Urban API data model

The elements in the graph can be explained as following:

ObjectDescription
Urban modelIt 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 databaseUrban 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.
ConfigConfiguration of the urban model used for general settings management.
Upgrade infoInformation on the upgrade status of the urban model.
Urban design databaseIt 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:

Urban database
Projects
Indicators
Urban database in the urban data model
Urban design database
Plan
Project
Urban design database in the urban data model

The elements in the graphs can be explained as following:

ObjectDescription
PlanLong-term urban planning on a large scale.
ProjectShort-term urban planning at the parcel level.
IndicatorIndicator data that provides additional insights about your urban model.

Plans

Plans
Branches
Building types
Metrics
Metric sources
Overlay types
Space-use types
Zone types
Metric values
Overlays
Parcels
Spaces
Zones
Plans in the urban data model

The elements in the graph can be explained as following:

ObjectDescription
Building typesBuilding types in the plan. A building type defines the mix of spaces used in a building.
Overlay typesOverlay 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 typesSpace-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 typesZone types in the plan. A zone type describes a certain combination of zoning code restrictions.
BranchesScenarios in the plan.
Metric sourcesList of sources used for metrics calculation.
Metric valuesValues stored for metrics.
MetricsMetrics 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.
OverlaysOverlays in the branch of the plan.
ParcelsParcels in the branch of the plan.
SpacesSpaces (floors of future buildings) in the branch of the plan.
ZonesZones in the branch of the plan.

Projects

Projects
Branches
Status types
LOD1 buildings
Point symbols
Polygon symbols
Projects in the urban data model
ObjectDescription
Status typesProject status type, describing the current stage of an urban project.
BranchesScenarios in the project.
LOD1 buildingsLow level of detail (LOD1) schematic buildings in the branch of the project.
Point symbolsPoint symbols representing trees, vehicles, and other urban furniture in the branch of the project.
Polygon symbolsPolygon 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:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
query {
  urbanModel(urbanModelId: "URBAN_MODEL_ID") {
    upgradeInfo {
      upgradeStatus
      message
    }
  }
}
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
query {
  urbanDesignDatabase(urbanDesignDatabaseId: "URBAN_DESIGN_DATABASE_ID") {
    upgradeInfo {
      upgradeStatus
      message
    }
  }
}

The upgradeStatus 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.
  • UpgradeAvailable: 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.
  • ServiceUnavailable: The upgrade status cannot be determined due to the servers being overloaded. Please try again later.
  • Invalid: Your urban model or urban design database is invalid and cannot be upgraded. Please contact support.

Depending on the upgradeStatus 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:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
mutation {
  upgradeUrbanModel(urbanModelId: "URBAN_MODEL_ID") {
    upgradeInfo {
      upgradeStatus
      message
    }
  }
}
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
mutation {
  upgradeUrbanDesignDatabase(urbanDesignDatabaseId: "URBAN_DESIGN_DATABASE_ID") {
    upgradeInfo {
      upgradeStatus
      message
    }
  }
}

The upgradeStatus 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.
  • ServiceUnavailable: The upgrade failed due to the servers being overloaded. Please try again later.
  • Invalid: Your urban model or urban design database is invalid and cannot be upgraded. Please contact support.

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