Use the programming languages

You can use the Urban API with any programming language and framework.

Currently, the Urban API documentation focuses on use with Python, though the concepts presented apply to other languages as well.

Choose your approach

While you can access the Urban API with nothing more than a standard HTTP client, there are GraphQL client libraries that make this process easier for the user. Client libraries can interact with the server in two ways:

  • directly with hand-written string queries, mutations, and subscriptions,
  • indirectly through objects generated for types defined in a GraphQL schema.

Although you can use both approaches to make API calls we highly recommend that you avoid hand-writing the operations. It is mainly because:

  • writing queries or mutations and later interpreting the results can be cumbersome and error-prone,
  • dealing with changes introduced in the schema or by user needs is more costly if done by hand.

Code snippets in the next paragraphs show how to start your interaction with the Urban API using both approaches.

Client-side libraries

While working with Python you will use a Simple GraphQL Client library (sgqlc). Open a terminal application and install sgqlc with the following command:

 
1
pip install sgqlc

Now you can reach a GraphQL endpoint and make calls to the Urban API.

Hand-written queries

To use a hand-written query in the string format open the text editor of choice and run the following code:

               
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from sgqlc.endpoint.http import HTTPEndpoint

url = 'https://urban-api.arcgis.com/graphql'

query = '''
query {
    urbanModels {
        id
        title
    }
}
'''

endpoint = HTTPEndpoint(url)
data = endpoint(query)

Once the query is complete, the data variable will contain JSON-encoded descriptions of urban models, such as:

                  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "data": {
    "urbanModels": [
      {
        "id": "e57f2982d5e74885979c975a904a6148",
        "title": "River Forest Urban Model"
      },
      {
        "id": "9c8bd4c0f6384b1c919c3a65a215713f",
        "title": "Utrecht"
      },
      {
        "id": "0f4c1fc028aa43d5b57d20c5fe5bb9c4",
        "title": "Grand-Lyon"
      }
    ]
  }
}

You can find more examples of hand-written queries and mutations in the Get started section.

Object queries

To write queries as objects you need a Python module, which includes classes corresponding to the Urban API schema. Since converting the existing schema to the Python module manually is time-consuming and error prone, sgqlc library automates this process in two steps.

  1. Use the introspection query to fetch the Urban API schema as JSON:

         
    1
    2
    3
    4
    5
    python -m sgqlc.introspection \
    --exclude-deprecated \
    --exclude-description \
    https://urban-api.arcgis.com/graphql \
    urban_api_schema.json
    
  2. Use the sgqlc code generator, which outputs a Python module straight from JSON:

     
    1
    sgqlc-codegen schema urban_api_schema.json urban_api_schema.py

Now that the Urban API schema is described in urban_api_schema.py, you can write the query as an object. Each object query is converted to a string form behind the scenes. As a result, the actual API call is exactly the same as when using hand-written queries.

                   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
from sgqlc.operation import Operation
from sgqlc.endpoint.http import HTTPEndpoint
from urban_api_schema import urban_api_schema as schema

url = 'https://urban-api.arcgis.com/graphql'

op = Operation(schema.Query) # module operation generates Queries and Mutations
urban_models = op.urban_models
urban_models.id()
urban_models.title()

endpoint = HTTPEndpoint(url)
json_data = endpoint(op)

# add the JSON data to the operation to interpret the results and produce convenient objects
obj = op + json_data
urban_models_data = obj.urban_models
for urban_model in urban_models_data:
    print(urban_model)

The above code snipet will print information about the Urban Models returned from the query, and will look similar to:

   
1
2
3
UrbanModel(id=fd45a15550cf4ea6b361e3c54c8d3ed1, title=Sample Urban Project)
UrbanModel(id=9dd5bed4a5b847c8a9feddeb410a5193, title=Modelo Curso ArcGIS Urban 2.0)
UrbanModel(id=e57f2982d5e74885979c975a904a6148, title=River Forest Urban Model)

For more information about sgqlc check the GitHub repository or read the documentation.

Keep learning

If you're just getting started with the Urban API we recommend exploring the code samples to find specific examples of the the API can do.

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