Calling the API

The 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.
  1. 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.
  1. 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.

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 using cURL with lon and lat:

curl --location --request POST 'https://graphql.probablefutures.org/graphql' \
--header 'Authorization: Bearer ACCESS_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation {\n  getDatasetStatistics(input: {\n        latitude: 40.7,\n        longitude: -73.9,\n        warmingScenario: \"1.5\"\n    }) {\n    datasetStatisticsResponses{\n        datasetId\n        highValue\n        lowValue\n        midValue\n        name\n        unit\n        warmingScenario\n    }\n  }\n}","variables":{}}'

Calling the API in JavaScript with lon and lat:

var headers = new Headers();
headers.append("Authorization", "Bearer {ACCESS_TOKEN_HERE}");
headers.append("Content-Type", "application/json");

var graphql = JSON.stringify({
  query: "mutation {\n      getDatasetStatistics(\n        input: {longitude: -73.9, latitude: 40.7, warmingScenario: \"1.0\", datasetId: 40104}\n      ) {\n        datasetStatisticsResponses {\n          datasetId\n          highValue\n          lowValue\n          midValue\n          name\n          unit\n          warmingScenario\n      }\n    }\n  }",
    variables: {}
});
var requestOptions = {
  method: 'POST',
  headers: headers,
  body: graphql,
};

fetch("https://graphql.probablefutures.org/graphql", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));

Calling the API in Python with lon and lat:

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + ACCESS_TOKEN_HERE
}
query = {
    "query": "mutation {\n      getDatasetStatistics(\n        input: {longitude: -73.9, latitude: 40.7, warmingScenario: \"1.0\", datasetId: 40104}\n      ) {\n        datasetStatisticsResponses {\n          datasetId\n          highValue\n          lowValue\n          midValue\n          name\n          unit\n          warmingScenario\n      }\n    }\n  }",
    "variables": {}
}
response = requests.post('https://graphql.probablefutures.org/graphql', headers=headers, json=query)

Calling the API using cURL with address and country:

curl --location --request POST 'https://graphql.probablefutures.org/graphql' \
--header 'Authorization: Bearer {ACCESS_TOKEN_HERE}' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation {\n      getDatasetStatistics(\n        input: {country: \"us\", address: \"121 East 48th Street, Apt. 123, New York, NY 10001\", warmingScenario: \"1.5\", datasetId: null}\n      ) {\n        datasetStatisticsResponses {\n          datasetId\n          highValue\n          lowValue\n          midValue\n          name\n          unit\n          warmingScenario\n          longitude\n          latitude\n      }\n    }\n}","variables":{}}'

Calling the API in JavaScript with address and country:

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {ACCESS_TOKEN_HERE}");
myHeaders.append("Content-Type", "application/json");

var graphql = JSON.stringify({
  query: "mutation {\n      getDatasetStatistics(\n        input: {country: \"us\", address: \"121 East 48th Street, Apt. 123, New York, NY 10001\", warmingScenario: \"1.5\", datasetId: null}\n      ) {\n        datasetStatisticsResponses {\n          datasetId\n          highValue\n          lowValue\n          midValue\n          name\n          unit\n          warmingScenario\n          longitude\n          latitude\n      }\n    }\n}",
  variables: {}
})
var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: graphql,
};

fetch("https://graphql.probablefutures.org/graphql", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Calling the API in Python with address and country:

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + ACCESS_TOKEN_HERE
}
query = {
    "query": "mutation {\n      getDatasetStatistics(\n        input: {country: \"us\", address: \"121 East 48th Street, Apt. 123, New York, NY 10001\", warmingScenario: \"1.5\", datasetId: null}\n      ) {\n        datasetStatisticsResponses {\n          datasetId\n          highValue\n          lowValue\n          midValue\n          name\n          unit\n          warmingScenario\n          longitude\n          latitude\n      }\n    }\n}",
    "variables": {}
}
response = requests.post('https://graphql.probablefutures.org/graphql', headers=headers, json=query)