Discover the Playground

This section gives a short introduction to the Urban API Playground. It also provides a few exemplary queries and mutations, which can be copied and pasted directly in the Playground. The examples cover basic Urban operations.

Get started

Open the Playground by loading the Urban API endpoint in a web browser. You can also explore the Playground in the API Reference section, which embeds the same GraphQL endpoint in the ArcGIS for developers webpage.

Press the Play button (1) to run an operation. The data returned by the operation, along with any errors, will be displayed in the pane next to the operation body. You can use two types of operations: a query or a mutation. A query is a read-only fetch operation, which requests data from a GraphQL service. A mutation is an operation that creates, modifies, or destroys data.

Note the Docs and Schema tabs (2) to the right. Open the Docs tab to see a complete set of queries and mutations along with their typed arguments and return values. You can drill-down into each part of the graph API by clicking on a given entry. Opening the Schema tab enables you to preview the whole GraphQL schema and download it as a file.

While writing operations, an autocomplete menu will list available fields. This can be triggered either by typing the first letters of a field's name or by pressing the auto-complete key shortcut which in most browsers is Ctrl+Space.

The IDE also supports advanced features such as using variables (3) and multiple tabs (4). Your queries and mutations will be automatically saved in local storage so you can visit the Playground later and use previous operations.

To use an authentication token with the IDE, append &token=MY_LONG_TOKEN_VALUE in the URL bar (5). This needs to be done separately for every tab that is open in the Playground.

Examples of queries

The query examples work with a Hardeeville example city, set specifically for this chapter. The urbanModelId is "8d199b9a69664aac9b2c3a69573600a6".

Query the urban models

Use the urbanModels query to list the id, title, and owner attributes of publicly accessible urban models. Note, that up to 10 models are returned by the server due to the default limit. To return more models, change the limit argument.

1
2
3
4
5
6
7
query {
  urbanModels {
    id
    title
    owner
  }
}

Query plans and projects

Use the following query to view the EventName, GlobalID, and the OwnerName attributes of the plans and projects present in an urban model. To select the urban model pass the appropriate urbanModelId as a query argument.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
query {
  urbanModel(urbanModelId: "8d199b9a69664aac9b2c3a69573600a6") {
    urbanDatabase {
      projects {
        attributes {
          EventName
          GlobalID
          OwnerName
        }
      }
      plans {
        attributes {
          EventName
          GlobalID
          OwnerName
        }
      }
    }
  }
}

Query projects using a geometryFilter

Use the following query to filter the projects using a geometryFilter. More specifically, get the GlobalID and EventName of the projects contained in a given polygon.

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
query {
  urbanModel(urbanModelId: "8d199b9a69664aac9b2c3a69573600a6") {
    urbanDatabase {
      projects(
        geometryFilter: {
          relationship: Contains
          polygon: {
            rings: [
              [
                [-9025899.749800002, 3799667.6687999964]
                [-9026098.991699995, 3799664.138700016]
                [-9026105.205599999, 3800014.8562000096]
                [-9025905.963599999, 3800018.3862000033]
                [-9025899.749800002, 3799667.6687999964]
              ]
            ]
            spatialReference: { wkid: 3857 }
          }
        }
      ) {
        attributes {
          GlobalID
          EventName
        }
      }
    }
  }
}

Examples of mutations

Set up your own Hardeeville example urban model to test the example mutations. Replace the id values provided in the examples ​​with the id values ​​of the model you created.

Create a new urban design database

Use createUrbanDesignDatabase mutation to create a new urban design database feature service, which stores your future plan or a project. Provide all the required attributes, which in this case are urbanModelId, type, and title. You can identify the required arguments in the Playground docs tab as the ones with an exclamation mark. Additionally, you may want to save the new design database in the same ArcGIS Online folder as the urban model. To achieve this, add a folderId attribute to the arguments.

1
2
3
4
5
6
7
8
mutation {
  createUrbanDesignDatabase(
    urbanModelId: "91a9f86012a64870a5a3a3fb9deb2XXX"
    type: Project
    title: "Hotel (Urban Design Database)"
    folderId: "95534b15e255459c98709a1555f9dXXX"
  )
}

Add a new project

Use the createProjects mutation to add a new project to the just created design database. Provide the required arguments EndDate, EventName, OwnerName, StartDate and geometry of the project. What is more, you must specify the sub-fields, which will be returned by the server in response. In the example below the only sub-field to be returned is the GlobalID attribute of the just created project.

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: "9c3ba6c054f945acabd1256bcbcf8XXX"
    projects: [
      {
        attributes: { EndDate: 1514847600000, EventName: "New event", OwnerName: "urban_agnieszka_dev", StartDate: 1459943798196 }
        geometry: {
          rings: [
            [
              [-9025620.6397, 3800089.023199998]
              [-9025647.4858, 3800060.340400003]
              [-9025675.7504, 3800082.3681000024]
              [-9025704.2087, 3800104.546599999]
              [-9025677.0497, 3800132.425999999]
              [-9025649.5113, 3800158.5407999977]
              [-9025621.2685, 3800137.468000002]
              [-9025593.723, 3800116.0534999967]
              [-9025620.6397, 3800089.023199998]
            ]
          ]
          spatialReference: { wkid: 3857 }
        }
      }
    ]
  ) {
    attributes {
      GlobalID
    }
  }
}

Edit an existing project

Use the updateProjects mutation to edit the description of the just created project. Note, that this example uses variables, which allows you to pass dynamic arguments in the query or mutation string. Provide a name for your mutation, for example, updateMyUrbanEvent, and declare the variables and their types. Next, replace the static value in the mutation body with $variableName.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
mutation updateMyUrbanEvent($studyArea: PolygonInput!, $myDescription: String!) {
  updateProjects(
    urbanDatabaseId: "9c3ba6c054f945acabd1256bcbcf8XXX"
    projects: [{ attributes: { GlobalID: "078D217A-1764-4AA2-9D23-6FCDA01F0XXX", Description: $myDescription }, geometry: $studyArea }]
  ) {
    attributes {
      GlobalID
      CustomID
      Description
    }
    geometry {
      rings
    }
  }
}

Finally, pass your input variables to the QUERY VARIABLES tab at the bottom of the Playground. The variables should be stored in a separate variables dictionary in the JSON format.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "studyArea": {
    "rings": [
      [
        [-9025620.6397, 3800089.023199998],
        [-9025647.4858, 3800060.340400003],
        [-9025675.7504, 3800082.3681000024],
        [-9025704.2087, 3800104.546599999],
        [-9025677.0497, 3800132.425999999],
        [-9025649.5113, 3800158.5407999977],
        [-9025621.2685, 3800137.468000002],
        [-9025593.723, 3800116.0534999967],
        [-9025620.6397, 3800089.023199998]
      ]
    ],
    "spatialReference": {
      "wkid": 3857
    }
  },
  "myDescription": "new updated description of the project"
}