Python sgqlc client library

This guide explains how to get started with the Simple GraphQL Client Python library (sgqlc).

Open a terminal application and install sgqlc with the following command:

1
pip install sgqlc

Choose your approach

Client libraries can interact with the GraphQL 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.

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

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:

   Use dark colors for code blocksCopy

   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:

   Use dark colors for code blocksCopy

   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 snippet 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.