Develop Your Own Interface for ClimateSERV API

getParameterTypes

Purpose: Get a list of the current supported statistical operation types and their code values.

URL: https://climateserv.servirglobal.net/api/getParameterTypes/

Supported Methods: GET

Returns: Array of supported statistical operation types.

[
  [0, "max", "Max"],
  [1, "min", "Min"],
  [2, "median", "Median"],
  [3, "range", "Range"],
  [4, "sum", "Sum"],
  [5, "avg", "Average"]
]
            

getFeatureLayers

Purpose: Get a list of the current feature layers included in the map for processing.

URL: https://climateserv.servirglobal.net/api/getFeatureLayers/

Supported Methods: GET

Returns: Array of feature layer info, including visibility, display name, and ID.

[
  {"visible": "true", "displayName": "Countries", "id": "country"},
  {"visible": "false", "displayName": "Admin #1", "id": "admin_1_earth"},
  {"visible": "false", "displayName": "Admin #2", "id": "admin_2_af"}
]
            

getClimateScenarioInfo

Purpose: Get information about the data structure of currently supported climate scenario datatypes. At this time there are a total of 10 ‘Climate_Ensembles’. Each ‘Climate_Ensemble’ can have 1, 2, or n ‘Climate_Variables’. The combination of ‘Climate_Ensemble’ and ‘Climate_Variable’ is unique and matches up to an individual dataset. (so 1 list of images per ‘Climate_Ensemble’ + ‘Climate_Variable’ combination.)

URL: https://climateserv.servirglobal.net/api/getClimateScenarioInfo/

Supported Methods: GET

Returns: JSON object.

{
  "unique_id": "87264db4-7297-4b99-aa22-a87fbd0e8a84",
  "RequestName": "getClimateScenarioInfo",
  "climate_DatatypeMap": [
    {
      "climate_Ensemble": "cfsv2_ens18",
      "climate_DataTypes": [
        {
          "dataType_Number": 76,
          "climate_Variable": "air_temperature"
        },
        {
          "dataType_Number": 77,
          "climate_Variable": "precipitation"
        }
      ]
    },
    {
      "climate_Ensemble": "ccsm4_ens01",
      "climate_DataTypes": [
        {
          "dataType_Number": 6,
          "climate_Variable": "air_temperature"
        },
        {
          "dataType_Number": 7,
          "climate_Variable": "precipitation"
        }
      ]
    }
   // Additional climate ensembles and data types...
  ],
  "climate_DataTypeCapabilities": [
    {
      "current_Capabilities": {
        "startDateTime": "2024-08-01",
        "endDateTime": "2025-01-28"
      }
    }
  ],
  "isError": false
}
            

submitDataRequest

Purpose: Submit a new asynchronous processing request to the server.

URL: https://climateserv.servirglobal.net/api/submitDataRequest/

Supported Methods

• GET
• POST

Parameters (input)

Due to increased demand in ClimateSERV services, a limit of 20 years of data per request has been implemented.

• datatype: (int), the unique datatype number for the dataset which this request operates on
• begintime: (string), start date for processing interval, format ("MM/DD/YYYY")
• endtime: (string), end date for processing interval, format ("MM/DD/YYYY")
• intervaltype: (int), enumerated value that represents which type of time interval to process (daily, monthly, etc)
• operationtype: (int), enumerated value representing the statistical operation to perform on the dataset
• geometry: (optional, object), the geometry defined by the user on the current client
• layerid: (optional), the layer ID selected by the user on the current client
• featureids: (optional), the feature IDs selected by the user on the current client
• isZip_CurrentDataType: (optional, string), blank defaults to 'False'. Sending anything through equates to 'True'. This lets the server know the job should zip up and return a full dataset.

Returns (output)

string: returns either the job ID (‘uniqueid’) as a UUID or an error message

Output Details

Submit the new data request and receive a job ID as a response. The returned job ID can then be used to retrieve results (see getDataFromRequest).

Example Request

If you are interested in retrieving CHIRPS data for a polygon and a time period, use the following request:

Example Output

    ["7e917e63-600d-4a1e-a069-ab8f73c9fcaf"]
  

getDataRequestProgress

Purpose: Get the current progress the server has made on processing the given request job ID.

URL: https://climateserv.servirglobal.net/api/getDataRequestProgress/

Supported Methods

• GET

Parameters (input)

• id: (string/UUID), the unique job ID (UUID format) of the job to check

Returns (output)

Array containing single float: returns the progress value as a float between 0.0 and 100.0 encapsulated in an array. If there is an error, a value of [-1] is returned.

Output Details

Request the server for the progress on processing the current job ID. The server returns a number that can be used to update the client progress bar. Repeat the request periodically to get updated progress.

Example Output

    [27.0]
  

getDataFromRequest

Purpose: Get the data from a job that has completed its processing.

URL: https://climateserv.servirglobal.net/api/getDataFromRequest/

Supported Methods

• GET

Parameters (input)

• id: (string/UUID), the unique job ID of the completed job

Returns (output)

object{}: Returns the data generated from the request, typically a list of numbers and dates. See the example below.

Output Details

Ask the server for the data related to a completed job by passing the job ID (UUID string). The response contains a list of data granules, each associated with a date and value.

Example Output

retObj.data                     // (Array[]) list of data granules that the processing job output created.

granule = retObj.data[n]         // (object), single data granule

granule.date                    // (string), readable date for current data granule. Format "d/m/y" (not fixed length)
granule.workid                  // (string), unique ID for the process item (used internally by the server).
granule.epochTime               // (string), Epoch time format for the date.
granule.value                   // (object), the key matches the statistical operation performed, and the value is the result of the operation for that data granule.
  

Example

{
    "data": [
        {
            "date": "1/1/2015",
            "workid": "01f4839f-7b9c-447f-b50f-0ca257c0a339",
            "epochTime": "1420092000",
            "value": {"max": 0.3055223822593689}
        },
        {
            "date": "1/2/2015",
            "workid": "58b6f7ea-5490-4ccd-a715-5e028407ad16",
            "epochTime": "1420178400",
            "value": {"max": 0.15552784502506256}
        },
        {
            // Additional granules can be listed here
            ....,
            ....,
        },
        {
            "date": "1/31/2015",
            "workid": "e021a12c-7346-4b7b-a273-bd39c7fde99b",
            "epochTime": "1422684000",
            "value": {"max": 4.206714630126953}
        }
    ]
}