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:
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:
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:
{
"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.
-
Use the introspection query to fetch the Urban API schema as JSON:
Use dark colors for code blocks Copy python -m sgqlc.introspection \ --exclude-deprecated \ --exclude-description \ https://urban-api.arcgis.com/graphql \ urban_api_schema.json
-
Use the sgqlc code generator, which outputs a Python module straight from JSON:
Use dark colors for code blocks Copy sgqlc-codegen schema urban_api_schema.json urban_api_schema.py
Now that the Urban API schema is described in urban
, 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.
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:
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.