Skip to content

Latest commit

 

History

History
168 lines (144 loc) · 5.6 KB

data-api-calls.md

File metadata and controls

168 lines (144 loc) · 5.6 KB
layout title nav_order parent
data-layout
Calling the data API
2
Data

Calling the data API

The data API is a GraphQL endpoint located at https://graphql.probablefutures.org/graphql where the query is a mutation with the following inputs:

1. Location data, in any of the following formats (required)

  • longitude: Type: number. Valid longitudes should be between -180 and 180.
  • latitude: Type: number. Valid latitudes should be between -90 and 90.
  • country: Generally recognized countries or country codes. Type: string. Example: "France" or "fr". Can be sent alone or with city and/or address.
  • city: Cities, villages, municipalities. Type: string. Should be sent with a country and/or address.
  • address: Any place name, postal addresses, individual residential or business addresses. Type: string. Can be sent alone or with city and/or country.

2. Warming scenario (optional)

  • warmingScenario: Specifies the warming scenario. Type: string or string array. Should be one or more of these values: "0.5", "1.0", "1.5", "2.0", "2.5", "3.0". For example, ["1", "2.5"]. If omitted, all 6 warming scenarios will be returned.

3. Dataset ID (optional)

  • datasetId: ID of the dataset requested, of type integer. If omitted the data for all datasets will be returned. See the full list of dataset IDs and their corresponding names on the maps page.

Example request

mutation {
  getDatasetStatistics(input: {
        country: "USA"
        city: "New York City"
        warmingScenario: "1.5"
        datasetId: 40104
    }) {
    datasetStatisticsResponses{
        datasetId
        midValue
        name
        unit
        warmingScenario
        latitude
        longitude
        info
        mapCategory
    }
  }
}

Responses

The response of the API includes a list of objects that has the following properties:

  • datasetId
  • highValue
  • lowValue
  • midValue
  • name
  • unit
  • warmingScenario
  • longitude
  • latitude
  • info
  • mapCategory ("heat", "water", "land", "other")
  • values

Some or all the fields can be requested to be part of the response.

{: .note } values contains 101 variables corresponding to the precentiles from 0 (the minimum) to 100 (the maximum). Read more about Statistical Percentiles & Range of Values. These values can specifically be used to draw charts like plot charts showing the chance of experiencing a sepcific outcome or range of outcomes. To understand this varibable a bit more and see examples of ways to draw these charts read about Data Charting.

Example response

{
  "data": {
    "getDatasetStatistics": {
      "datasetStatisticsResponses": [
        {
          "datasetId": 40104,
          "midValue": "25.0",
          "name": "Days above 32°C (90°F)",
          "unit": "days",
          "warmingScenario": "1.5",
          "latitude": 40.8,
          "longitude": -74,
          "info": {},
          mapCategory: "heat"
        }
      ]
    }
  }
}

The "info" property is an object that provides additional details related to the query, if there any, such as for the climate zones dataset. Here is an example of the "info" property displaying the name of the climate zone that is expected in a 1.0°C warming scenario:

{
  "datasetId": 40901,
  "midValue": "33.0",
  "name": "Climate zones",
  "unit": "class",
  "warmingScenario": "1.0",
  "longitude": -74,
  "latitude": 40.8,
  "info": {
    "climateZoneName": "Temperate humid"
  }
}

Applied examples

Calling the API with lon and lat:

cURL
JS
Python

Calling the API with address and country:

cURL
JS
Python

Try it out yourself

Get the token

Run Code

Call the API

Run Code
Show More