Handling spatial references

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.

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 references in ArcGIS Urban

ArcGIS Urban supports a range of geographic and projected coordinate systems. Depending on the used spatial reference, you will work with a local or global urban model. See Understanding local and global urban models to learn which coordinate systems are currently supported.

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

• When you create a new urban model, you can specify a coordinate system for your model. If you do not provide a spatialReference as an input in the mutation, Web Mercator (wkid:3857) is used by default.

  As an example, create a new local urban model located in Zurich, Switzerland, using the CH1903+ LV95 coordinate system (wkid:2056):

  Use dark colors for code blocksCopy

  1
  2
  3
  mutation {
    createUrbanModel(title: "Zurich", spatialReference: { wkid: 2056 })
  }

• When you mutate the data, you must provide the input geometry in the same coordinate system as the urban model it belongs to. The Urban API does not project data.

  As an example, use the following operation to create a new project with geometry in a local European spatial reference ETRS89 / UTM zone 32N (wkid:25832):

  Use dark colors for code blocksCopy

  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
  30
  mutation {
    createProjects(
      urbanDatabaseId: "URBAN_DESIGN_DATABASE_ID"
      projects: [
        {
          attributes: { EndDate: 1659265775610, StartDate: 1626779375610, EventName: "EVENT_NAME", OwnerName: "OWNER_NAME" }
          geometry: {
            spatialReference: { wkid: 25832 }
            rings: [
              [
                [577401.1322, 5917717.1711]
                [577406.3402, 5917721.714]
                [577416.0492, 5917730.184]
                [577417.3802, 5917728.4841]
                [577426.3942, 5917717.9151]
                [577418.8132, 5917711.3021]
                [577411.7962, 5917705.1801]
                [577409.2822, 5917708.008]
                [577401.1322, 5917717.1711]
              ]
            ]
          }
        }
      ]
    ) {
      attributes {
        GlobalID
      }
    }
  }

• When you query the data, Urban API will return the geometry in the coordinate system defined for this urban model. 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 are returned with wkid:25832.

  Use dark colors for code blocksCopy

  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:

  Use dark colors for code blocksCopy

  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
  {
    "data": {
      "urbanDesignDatabase": {
        "projects": [
          {
            "geometry": {
              "rings": [
                [
                  [577401.1322, 5917717.1711]
                  [577406.3402, 5917721.714]
                  [577416.0492, 5917730.184]
                  [577417.3802, 5917728.4841]
                  [577426.3942, 5917717.9151]
                  [577418.8132, 5917711.3021]
                  [577411.7962, 5917705.1801]
                  [577409.2822, 5917708.008]
                  [577401.1322, 5917717.1711]
                ]
              ],
              "spatialReference": {
                "wkid": 25832
              }
            }
          }
        ]
      }
    }
  }