Handling spatial references

A provides information about the 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):

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

    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.

    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
    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
                }
              }
            }
          ]
        }
      }
    }

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

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close