======================
SoilGrids API User Guide
======================

.. contents:: Table of Contents
   :local:
   :depth: 2

This guide provides step-by-step instructions on how to use the SoilGrids API to retrieve soil characteristics for a specific location.
The aim is to replicate the logic in the CFT, which retrieves the soil class for a given latitude and longitude.
for more information on SoilGrids API visit https://rest.isric.org/soilgrids/v2.0/docs

Setup
=====
Before we begin, make sure you have a tool to make HTTP requests. This could be a command-line tool like ``curl``, a library in a programming language (e.g., ``requests`` in Python), or a graphical interface like Postman.

Construct the URL
=================
The URL you will request data from depends on the endpoint you are using. There are two endpoints used in the Python function: ``properties`` and ``classification``.

The base URL is: ``https://rest.isric.org/soilgrids/v2.0/``

For the ``properties`` endpoint, the URL is:

.. code-block:: none

    https://rest.isric.org/soilgrids/v2.0/properties/query?lon={longitude}&lat={latitude}&property=clay&property=sand&depth=0-5cm&value=mean&value=uncertainty

For the ``classification`` endpoint, the URL is:

.. code-block:: none

    https://rest.isric.org/soilgrids/v2.0/classification/query?lon={longitude}&lat={latitude}&number_classes=0

Replace ``{longitude}`` and ``{latitude}`` with the actual longitude and latitude of the location you're interested in.


Make the Request
================
Send a GET request to the constructed URL. The server will return a JSON object with the requested data.

Parse the Response
==================
The response from the ``properties`` endpoint contains mean values for the ``clay`` and ``sand`` properties. You will need to parse the JSON to extract these values.

If the mean value of ``sand`` is greater than 70 and ``clay`` is less than 8, the soil is classified as sandy. If not, you will need to make another request to the ``classification`` endpoint.

The response from the ``classification`` endpoint contains a ``wrb_class_name`` which represents the soil class. This class name can be mapped to a set of predefined soil characteristics.

Error Handling
==============
If the response status code is not 200, handle the error appropriately. Depending on your application, you may want to retry the request, log the error, or inform the user.

Use the Data
============
Once you have the soil class, you can use this information in your application.

Examples
========
Below are examples of how to use the SoilGrids API in different programming languages:

Using the Soil Grids Web API interface
--------------------------------------

The SoilGrids Web API interface is a graphical interface that allows you to make requests to the SoilGrids API and view the response. You can use this interface to test your requests and see the response.

To use the interface to replicate the results shown in the CFT, follow these steps:

Sand and Clay

* Navigate to `https://rest.isric.org/soilgrids/v2.0/ <https://rest.isric.org/soilgrids/v2.0/>`_
* Select the 3rd request in the list: ``properties/query``
* Click on the ``Try it out`` button
* Substitute the ``{longitude}`` and ``{latitude}`` placeholders with the actual longitude and latitude of the location you're interested in
* Remove all properties except ``clay`` and ``sand``
* For ``Depth``, select ``0-5cm``
* For ``Value``, select ``mean`` and ``uncertainty``
* Press the ``Execute`` button

Determining the Soil Class

* Navigate to `https://rest.isric.org/soilgrids/v2.0/ <https://rest.isric.org/soilgrids/v2.0/>`_
* Select the 1st request in the list: ``classification/query``
* Click on the ``Try it out`` button
* Substitute the ``{longitude}`` and ``{latitude}`` placeholders with the actual longitude and latitude of the location you're interested in
* For ``Number of classes``, select ``0``
* Press the ``Execute`` button



Python
------
.. code-block:: python

    import requests

    # replace with actual longitude and latitude
    longitude = 0
    latitude = 0

    # make request to properties endpoint
    response = requests.get(f"https://rest.isric.org/soilgrids/v2.0/properties/query?lon={longitude}&lat={latitude}&property=clay&property=sand&depth=0-5cm&value=mean&value=uncertainty")

    # parse response
    data = response.json()
    # continue with your application logic...

Node.js
-------
.. code-block:: javascript

    const axios = require('axios');

    // replace with actual longitude and latitude
    const longitude = 0;
    const latitude = 0;

    // make request to properties endpoint
    axios.get(`https://rest.isric.org/soilgrids/v2.0/properties/query?lon=${longitude}&lat=${latitude}&property=clay&property=sand&depth=0-5cm&value=mean&value=uncertainty`)
      .then(response => {
        const data = response.data;
        // continue with your application logic...
      })
      .catch(error => {
        console.error(error);
      });

Curl (Command Line)
-------------------
.. code-block:: bash

    # replace with actual longitude and latitude
    longitude=0
    latitude=0

    # make request to properties endpoint
    curl "https://rest.isric.org/soilgrids/v2.0/properties/query?lon=$longitude&lat=$latitude&property=clay&property=sand&depth=0-5cm&value=mean&value=uncertainty"

Remember to replace the ``0`` values for ``longitude`` and ``latitude`` with the actual coordinates of the location you're interested in.

Soil Characteristics Mapping
============================
The soil class obtained from the API response corresponds to a set of soil characteristics defined in your application. Below is a table that outlines this mapping:

.. list-table:: Soil Class Mapping
   :widths: 25 25 50
   :header-rows: 1

   * - Soil Class (API Response)
     - Soil Characteristic (Application Value)
     - Description
   * - Sandy Soils (mean sand > 70%, mean clay < 8%)
     - 1
     - Sandy Soils
   * - Gleysols
     - 2
     - Wetland Soils
   * - Andosols
     - 3
     - Volcanic Soils
   * - Podzols
     - 4
     - Spodic Soils
   * - Leptosols, Vertisols, Kastanozems, Chernozems, Phaeozems, Luvisols, Alisols, Albeluvisols, Solonetz, Calcisols, Gypsisols, Umbrisols, Cambisols, Regosols
     - 5
     - High Activity Clay Soils
   * - Others (or when soil class is not available)
     - 6
     - Low Activity Clay Soils

Please note that if the mean sand content is greater than 70% and the mean clay content is less than 8%, the soil is classified as sandy. Otherwise, the classification endpoint is used to determine the soil class.