Skip to content
Snippets Groups Projects
Select Git revision
  • tutorial-quarto
  • diana
  • main default protected
3 results
Blame Permalink
README.md 5.06 KiB

WoSIS Graphql API Masterclass

This masterclass aims to explain and exemplify the use of WoSIS Graphql API.

Table of contents

Introduction

WoSIS stands for 'World Soil Information Service', a large database based on PostgreSQL + API's, workflows, dashboards etc., developed and maintained by ISRIC, WDC-Soils. It provides a growing range of quality-assessed and standardised soil profile data for the world. For this, it draws on voluntary contributions of data holders/providers worldwide.

The source data come from different types of surveys ranging from systematic soil surveys (i.e., full profile descriptions) to soil fertility surveys (i.e., mainly top 20 to 30 cm). Further, depending on the nature of the original surveys the range of soil properties can vary greatly (see https://essd.copernicus.org/articles/12/299/2020/).

The quality-assessed and standardised data are made available freely to the international community through several webservices, this in compliance with the conditions (licences) specified by the various data providers. This means that we can only serve data with a so-called 'free' licence to the international community (https://data.isric.org/geonetwork/srv/eng/catalog.search#/search?any=wosis_latest). A larger complement of geo-referenced data with a more restrictive licence can only be used by ISRIC itself for producing SoilGrids maps and similar products (i.e. output as a result of advanced data processing). Again, the latter map layers are made freely available to the international community (https://data.isric.org/geonetwork/srv/eng/catalog.search#/search?resultType=details&sortBy=relevance&any=soilgrids250m%202.0&fast=index&_content_type=json&from=1&to=20).

WoSIS workflow WoSIS workflow for ingesting, processing and disseminating data.

During this master class, you will first learn what GraphQL and API (application programming interface) are. Next, using guided steps, we will explore the basics of WoSIS and GraphQL via a grahical interface. From that point onwards we will slowly increase complexity and use WoSIS data. Building upon this, we will how to create code that uses soil data.

The workshop requires no previous knowledge of WoSIS or GraphQL. However, it is advisable to have basic coding knowledge on the Python or R language.

The aim of this masterclass is to provide clear documentation on how to use WoSIS Graphql API.

WoSIS public products

WoSIS data can be accessed via OGC services and a GraphQL API

OGC services was the initial available way to download and access WoSIS. You can find more information on how to access WoSIS using OGC services at https://www.isric.org/explore/wosis/accessing-wosis-derived-datasets

Recently we developed a GraphQL API and the aim of the masterclass is to show and describe how to use this tool to download and explore WoSIS data.

What is GraphQL?

GraphQL is a query language for API's. GraphQL isn't tied to any specific database or storage engine and is instead backed by your existing code and data.

If you are new to GraphQL it might be good to check the official documentation: https://graphql.org/learn/

Requirements

In order to move forward make you dont need to have any extra tools apart from a browser.

However, if your aim is to use this API in scripting then its advizable to have knowladge in at least one of the folowing languages:

  • Python
  • R

API root endpoint and web interfaces

Root endpoint

WoSIS GraphQL API root endpoint is can be found at:

https://dev-graphql-isric.containers.wurnet.nl/wosis/graphql (NOTE TO MYSELF: CHANGE URL TO PROD VERSION WHEN READY)

This is the main GraphQL root endpoint. If you are an advanced GraphQL user and you use a custom script or a GraphQL client this is what you sould use.

Nonetheless if you click on the above link using a browser you'll probably get the folowing error message:

{"errors":[{"message":"Only `POST` requests are allowed."}]}

This is expected because this GraphQL endpoint expects POST requests and not GET requests.

To simplify endusers we provide two Web interfaces IDE's that can be used in a graphical way to explore and access the data.

Web interfaces IDE's

We provide the folowing interactive in-browser GraphQL IDE's

(NOTE TO MYSELF: CHANGE URL TO PROD VERSION WHEN READY)

For the exercises on this masterclass we'll use graphiql but you are free to use the one you prefer most.

Explore current schema

WoSIS

Explore the documentation

First queries

Filtering

Spatial queries

Using variables

Pagination concepts

Scripting

Python examples

R examples