NAV
shell python javascript

Introduction

Welcome to the Meersens API documentation. These APIs are designed to let you retrieve and integrate environmental data seemlessly into your own services and products.

Using these APIs, you'll be able to retrieve information on:

For each of these APIs, endpoints allow you to request various data, depending on what information better suit your business case. It may include:

Theses APIs are based on the RESTful architecture, returning either requested data or a described error message.

In case you need additional information, please do not hesitate to contact us.

Authentication

To authorize a request, use this code:

import requests

requests.get("api_endpoint_here", headers={
  'apikey': 'your_api_key'
})

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("api_endpoint_here",{
  headers: {'apikey': 'your_api_key'}
})

Meersens uses API keys to allow access to the API. You can obtain your API key by entering in contact with us through our contact form.

Meersens expects for the API key to be included in all API requests to the server in a header that looks like the following:

apikey: your_api_key

Data confidence

Data quality may vary, mostly depending on the geographic area you're requesting or on the timeframe you're interested in. In order to materialize this variation, each result retrieved through the Meersens API comes with a confidence index, from 1 to 5:

Internationalization

All environmental API are internatiolized and available in multiple languages. By default, results and data are returned in English, but you can easily change the output language by setting the Accept-Language header to the desired language.

Currently Meersens environmental APIs support the following languages:

Please note that if you request an API using an unsupported language, the default English language will be returned.

Air quality

The air quality API lets you request air quality data for a specific location. Retrieved information includes pollutant concentration levels, data confidence, comparison with W.H.O applicable standards & norms and generic health recommendations.
Major pollutants are available, including:

Air quality indexes

In order to let you easily interpretate environmental data, each one is associated to an environmental index. This index is designed to represent a human-readable assessment of a given environmental quality, simplifying the readings of raw pollutants concentrations and emphasizing eventual country specificities given pollutants levels interpretation.

For Air Quality, Meersens currently supports the following indexes:

ID Name  Numeric Description Pollutants
meersens Meersens Air Quality Index true Meersens proprietary Air Quality Index pm25, pm10, o3, no2, so2
bel_aqi BE Air Quality Index true Belgium BelAQI Air Quality Index pm25, pm10, o3, no2
cn_aqi CN Air Quality Index true China MEP Air Quality Index pm25, pm10, o3, no2, so2
eu_aqi EU Air Quality Index false European Environmental Agency Air Quality Index pm25, pm10, o3, no2, so2
fra_aqi FR Air Quality Index false France ATMO Air Quality Index pm25, pm10, o3, no2, so2
usa_aqi US Air Quality Index true US Environmental Protection Agency (EPA) Air Quality Index pm25, pm10, o3, no2, so2, co

Air quality current conditions

import requests

requests.get("https://api.meersens.com/environment/public/air/current", headers={
  'apikey': 'your_api_key'
}, params={
  lat: 1.234,
  lng: 5.678
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/air/current?lat=1.234&lng=5.678" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/air/current",{
  params: { 
    lat: 1.234,
    lng: 5.678
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "datetime": "2021-11-08T21:00:00.000Z",
    "index": {
        "index_type": "meersens",
        "index_name": "Meersens",
        "qualification": "Degraded",
        "icon": null,
        "color": "#adc704",
        "value": 34.13,
        "main_pollutants": [
            "pm25"
        ]
    },
    "pollutants": {
        "no2": {
            "shortcode": "NO2",
            "name": "Nitrogen dioxide",
            "unit": "µg/m³",
            "found": true,
            "value": 16.8,
            "confidence": 4.5,
            "index": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "Good",
                "icon": null,
                "color": "#05b3a4",
                "description": "That air quality level won’t present a risk for health for an exposure time superior to decades",
                "value": 14.28
            }
        },
        "co": {...},
        "o3": {...},
        "pm10": {...},
        "pm25": {...},
        "so2": {...}
    },
    "health_recommendations": {
        "all": "Degraded air quality can cause irritation of the respiratory tract and cause respiratory discomfort.",
        "family": "Children with an immature respiratory system are more impacted by poor air quality. Outdoor activities can be maintained as long as there is no respiratory or cardiac discomfort.",
        "sport": "Physical activities cause an increase in respiratory rate which leads to increased exposure to pollutants and potentially to symptoms resulting from them.",
        "pregnancy": "Exposure to pollutants can affect the fetus and pregnancy (lower birth weight, preterm delivery ...)",
        "respiratory": "Air pollution can worsen respiratory pathologies such as asthma, COPD, chronic bronchitis ...",
        "elderly": "With age, the respiratory system can become weakened and pollution can exacerbate respiratory problems",
        "cardiovascular": "Air pollution has been implicated in the development or aggravation of cardiovascular disease"
    }
}

Returns current information about air quality conditions for a specific location.

Path

GET https://api.meersens.com/environment/public/air/current

Query Parameters

Parameter Type   Description Required
lat number Latitude of the location to compute air quality conditions at. In WGS84 format. true
lng number Longitude of the location to compute air quality conditions at. In WGS84 format. true
index_type string Unique identifier of the desired output air quality index. Use reserved keyword local to get the locally applicable index at the point you're requesting data. false
(default:meersens)
health_recommendations boolean Indicates whether health recommendations should be retrieved for this air quality levels or not. false
(default:false)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found.
datetime string ISO_8601 UTC datetime indicating the time the data refers to.
index  object Air quality index object.
index.index_type  string Unique identifier of the returned air quality index.
index.index_name  string Name of the returned air quality index.
index.qualification  string Air quality index textual representation.
index.description  string Air quality index textual assessment.
index.icon  string Air quality level associated icon (if any, otherwise null).
index.color  string Air quality level hexadecimal color code.
index.value  number Air quality level value (for numeric indexes only, otherwise null).
index.main_pollutants  array Array of main pollutants identifiers.
pollutants  object Dictionary of available pollutants at the requested point.
pollutants.shortcode  string Pollutant textual shortcode.
pollutants.name  string Pollutant full name.
pollutants.unit  string Unit in which the pollutant value is returned.
pollutants.found  boolean Whether the pollutant value has been found.
pollutants.value  number Value of the pollutant in specified unit.
pollutants.confidence  number Pollutant value confidence.
pollutants.index  object Pollutant specific index information
pollutants.index.index_type  string Unique identifier of the returned air quality index.
pollutants.index.index_name  string Name of the returned air quality index.
pollutants.index.qualification  string Air quality index textual representation.
pollutants.index.description  string Air quality index textual assessment.
pollutants.index.icon  string Pollutant level associated icon (if any, otherwise null).
pollutants.index.color  string Pollutant level hexadecimal color code.
pollutants.index.value  number Pollutant level index value (for numeric indexes only, otherwise null).
health_recommendations object Dictionary of health recommendations for various population categories, including:
-all : general population
-family : populations with childrens
-sport : sports populations
-pregnancy : pregnant populations
-elderly : elderly populations
-respiratory : populations with respiratory diseases
-cardiovascular : populations with cardiovascular diseases

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

Air quality history

import requests

requests.get("https://api.meersens.com/environment/public/air/history", headers={
  'apikey': 'your_api_key'
}, params={
  lat: 1.234,
  lng: 5.678,
  from: '2021-01-01T00:00:00Z',
  to: '2021-01-02T00:00:00Z',
  page: 0
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/air/history?lat=1.234&lng=5.678&from=2021-01-01T00:00:00Z&to=2021-01-02T00:00:00Z&page=0" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/air/forecast",{
  params: { 
    lat: 1.234,
    lng: 5.678,
    from: '2021-01-01T00:00:00Z',
    to: '2021-01-02T00:00:00Z',
    page: 0
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "values": [
        {
            "datetime": "2021-11-07T22:00:00.000Z",
            "pollutants": {    
                "no2": {
                    "found": true,
                    "name": "Nitrogen dioxide",
                    "shortcode": "NO2",
                    "unit": "µg/m³",
                    "value": 11.3,
                    "confidence": 4.5,
                    "index": {
                        "index_type": "meersens",
                        "index_name": "Meersens",
                        "qualification": "Good",
                        "icon": null,
                        "color": "#05b3a4",
                        "description": "That air quality level won’t present a risk for health for an exposure time superior to decades",
                        "value": 9.61
                    }
                },
                "co": {...},
                "o3": {...},
                "pm10": {...},
                "pm25": {...},
                "so2": {...}
            },
            "index": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "Correct",
                "icon": null,
                "color": "#44b001",
                "value": 32.62,
                "main_pollutants": [
                    "o3"
                ]
            },
            "found": true
        },
        {...}
    ],
    "page": {
        "totalElements": 24,
        "totalPages": 4,
        "pageNumber": 0,
        "size": 6
    }
}

Returns paginated hourly history air quality data at a given location. For each hour included in the requested timeframe, the pollutants concentrations will be retrieved (if found), along with the computed air quality index. Each returned page will contain up to 6 time points entries.

Path

GET https://api.meersens.com/environment/public/air/history

Query Parameters

Parameter Type   Description Required
lat number Latitude of the location to compute air quality conditions at. In WGS84 format. true
lng number Longitude of the location to compute air quality conditions at. In WGS84 format. true
from string ISO_8601 UTC datetime (including timezone) that indicates the starting date of the history timeframe data. false
(default:24hours ago)
to string ISO_8601 UTC datetime (including timezone) that indicates the ending date of the history timeframe data. false
(default:beginning of current hour)
index_type string Unique identifier of the desired output air quality index. Use reserved keyword local to get the locally applicable index at the point you're requesting data. false
(default:meersens)
page number The number of the page to return among the pages of results. false (default: 0)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found over the period.
values array Array of hourly air quality values.
values.datetime string ISO_8601 UTC datetime indicating the time the data refers to for this hourly entry.
values.index  object Air quality index object for this hourly entry.
values.index.index_type  string Unique identifier of the returned air quality index.
values.index.index_name  string Name of the returned air quality index.
values.index.qualification  string Air quality index textual representation.
values.index.description  string Air quality index textual assessment.
values.index.icon  string Air quality level associated icon (if any, otherwise null).
values.index.color  string Air quality level hexadecimal color code.
values.index.value  number Air quality level value (for numeric indexes only, otherwise null).
values.index.main_pollutants  array Array of main pollutants identifiers.
values.pollutants  object Dictionary of available pollutants at the requested point for this hourly entry.
values.pollutants.shortcode  string Pollutant textual shortcode.
values.pollutants.name  string Pollutant full name.
values.pollutants.unit  string Unit in which the pollutant value is returned.
values.pollutants.found  boolean Whether the pollutant value has been found.
values.pollutants.value  number Value of the pollutant in specified unit.
values.pollutants.confidence  number Pollutant value confidence.
values.pollutants.index  object Pollutant specific index information
values.pollutants.index.index_type  string Unique identifier of the returned air quality index.
values.pollutants.index.index_name  string Name of the returned air quality index.
values.pollutants.index.qualification  string Air quality index textual representation.
values.pollutants.index.description  string Air quality index textual assessment.
values.pollutants.index.icon  string Pollutant level associated icon (if any, otherwise null).
values.pollutants.index.color  string Pollutant level hexadecimal color code.
values.pollutants.index.value  number Pollutant level index value (for numeric indexes only, otherwise null).
page object Object containing information about the pagination of the response.
page.totalElements number The total amount of air quality values.
page.totalPages number The amount of pages of air quality values.
page.pageNumber number The number of the page currently returned.
page.size number The amount of air quality values returned per page.

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

Air quality forecast

import requests

requests.get("https://api.meersens.com/environment/public/air/forecast", headers={
  'apikey': 'your_api_key'
}, params={
  lat: 1.234,
  lng: 5.678,
  from: '2021-01-01T00:00:00Z',
  to: '2021-01-02T00:00:00Z',
  page: 0
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/air/forecast?lat=1.234&lng=5.678&from=2021-01-01T00:00:00Z&to=2021-01-02T00:00:00Z&page=0" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/air/forecast",{
  params: { 
    lat: 1.234,
    lng: 5.678,
    from: '2021-01-01T00:00:00Z',
    to: '2021-01-02T00:00:00Z',
    page: 0
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "values": [
        {
            "datetime": "2021-11-07T22:00:00.000Z",
            "pollutants": {    
                "no2": {
                    "found": true,
                    "name": "Nitrogen dioxide",
                    "shortcode": "NO2",
                    "unit": "µg/m³",
                    "value": 11.3,
                    "confidence": 4.5,
                    "index": {
                        "index_type": "meersens",
                        "index_name": "Meersens",
                        "qualification": "Good",
                        "icon": null,
                        "color": "#05b3a4",
                        "description": "That air quality level won’t present a risk for health for an exposure time superior to decades",
                        "value": 9.61
                    }
                },
                "co": {...},
                "o3": {...},
                "pm10": {...},
                "pm25": {...},
                "so2": {...}
            },
            "index": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "Correct",
                "icon": null,
                "color": "#44b001",
                "value": 32.62,
                "main_pollutants": [
                    "o3"
                ]
            },
            "found": true
        },
        {...}
    ],
    "page": {
        "totalElements": 24,
        "totalPages": 2,
        "pageNumber": 0,
        "size": 6
    }
}

Returns paginated hourly forecast air quality data at a given location. For each hour included in the requested timeframe, the pollutants concentrations will be retrieved (if found), along with the computed air quality index. The maximum timeframe allowed to be requested is 96 hours, meaning 4 days. Each returned page will contain up to 6 time points entries.

Path

GET https://api.meersens.com/environment/public/air/forecast

Query Parameters

Parameter Type   Description Required
lat number Latitude of the location to compute air quality conditions at. In WGS84 format. true
lng number Longitude of the location to compute air quality conditions at. In WGS84 format. true
from string ISO_8601 UTC datetime (including timezone) that indicates the starting date of the forecast timeframe data. false
(default:beginning of current hour)
to string ISO_8601 UTC datetime (including timezone) that indicates the ending date of the forecast timeframe data. false
(default:24hours from now)
index_type string Unique identifier of the desired output air quality index. Use reserved keyword local to get the locally applicable index at the point you're requesting data. false
(default:meersens)
page number The number of the page to return among the pages of results. false (default: 0)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found over the period.
values array Array of hourly air quality values.
values.datetime string ISO_8601 UTC datetime indicating the time the data refers to for this hourly entry.
values.index  object Air quality index object for this hourly entry.
values.index.index_type  string Unique identifier of the returned air quality index.
values.index.index_name  string Name of the returned air quality index.
values.index.qualification  string Air quality index textual representation.
values.index.description  string Air quality index textual assessment.
values.index.icon  string Air quality level associated icon (if any, otherwise null).
values.index.color  string Air quality level hexadecimal color code.
values.index.value  number Air quality level value (for numeric indexes only, otherwise null).
values.index.main_pollutants  array Array of main pollutants identifiers.
values.pollutants  object Dictionary of available pollutants at the requested point for this hourly entry.
values.pollutants.shortcode  string Pollutant textual shortcode.
values.pollutants.name  string Pollutant full name.
values.pollutants.unit  string Unit in which the pollutant value is returned.
values.pollutants.found  boolean Whether the pollutant value has been found.
values.pollutants.value  number Value of the pollutant in specified unit.
values.pollutants.confidence  number Pollutant value confidence.
values.pollutants.index  object Pollutant specific index information
values.pollutants.index.index_type  string Unique identifier of the returned air quality index.
values.pollutants.index.index_name  string Name of the returned air quality index.
values.pollutants.index.qualification  string Air quality index textual representation.
values.pollutants.index.description  string Air quality index textual assessment.
values.pollutants.index.icon  string Pollutant level associated icon (if any, otherwise null).
values.pollutants.index.color  string Pollutant level hexadecimal color code.
values.pollutants.index.value  number Pollutant level index value (for numeric indexes only, otherwise null).
page.totalElements number The total amount of air quality values.
page.totalPages number The amount of pages of air quality values.
page.pageNumber number The number of the page currently returned.
page.size number The amount of air quality values returned per page.

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

Air quality heatmap

Meersens offers thanks to a geographic server the access to its air quality data. This server follows the rules of the standards OGC (Open Geospatial Consortium) which establish the protocol to access geographical data between a server and a client.

To display the heatmap of a specific pollutant or the index representation of those Meersens deeply recommend the use of WMS (Web Map Service) define by the OGC. WMS specifies different request types:

Path

import requests

requests.get("https://tiles.meersens.com/wms", headers={
  'apikey': 'your_api_key'
}, params={
  SERVICE: "GetMap",
  VERSION: "1.1.1",
  FORMAT: "image/png",
  TRANSPARENT: true,
  WIDTH: 512,
  HEIGHT: 512,
  SRS: "EPSG:3857",
  tiled: true,
  layers: {layer_name}
})

# With shell, you can just pass the correct header with each request
curl "https://tiles.meersens.com/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&FORMAT=image%2Fpng&TRANSPARENT=true&WIDTH=512&HEIGHT=512&SRS=EPSG%3A3857tiled=true&layers={layer_name}" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://tiles.meersens.com/wms",{
  params: { 
    SERVICE: "GetMap",
    VERSION: "1.1.1",
    FORMAT: "image/png",
    TRANSPARENT: true,
    WIDTH: 512,
    HEIGHT: 512,
    SRS: "EPSG:3857",
    tiled: true,
    layers: {layer_name}
  }
  headers: {'apikey': 'your_api_key'}
})

GET https://tiles.meersens.com/wms

Example: https://tiles.meersens.com/geowebcache/service/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&FORMAT=image%2Fpng&TRANSPARENT=true&tiled=true&layers=meersens:gam_meersens_2021_11_16_10h00&WIDTH=512&HEIGHT=512&SRS=EPSG%3A3857&BBOX=-2504688.542848654,5009377.085697312,-1252344.271424327,6261721.357121639

Authentication

The Meersens tile server use the same authentication mechanism than 'regular' APIs. So please request air quality tiles while providing the apikey header filled with your Meersens API key.

Query Parameters

All described parameters below are mandatory.

Parameter Type   Description Value
SERVICE string WMS service to consume GetMap
(mandatory)
VERSION string WMS version to use 1.1.1
(mandatory)
FORMAT string Output format of the returned tile image/png
(mandatory)
TRANSPARENT boolean Transparency of the returned tile true
(mandatory)
WIDTH number Width (in pixels) of the returned tile 512
(mandatory)
HEIGHT number Height (in pixels) of the returned tile 512
(mandatory)
SRS string Spatial reference system EPSG:3857
(mandatory)
tiled boolean Tile attribute of the returned data true
(mandatory)
layers string Layer name to request See data catalog to learn how to construct layer name

Please note that for now, only 512px x 512px tiles will be returned, projected using EPSG:3857.

Data catalog

Meersens offers multiple layers to display a specific air pollutant or their aggregation with an index/standard. Each hour a new layer is released and can be access to have the current conditions. Meersens also maintain the layers for the last 24 hours conditions. All these information can be accessed thanks to the GetCapabilities URL. Currently the forecast conditions are not exposed on the geographic server, but this subject can be discussed if the need arises.

For each hour, Meersens produces multiple layers, one for each pollutant and one for each standard. The pattern of the layer name is :

meersens:gam_{layer_id}_{YYYY_MM_DD_HHh00}

(e.g meersens:gam_pm25_conc_2021_11_09_18h00, meersens:gam_meersens_2021_11_10_12h00)

The date parameter present in the layer name should be in UTC timezone.

The layer_id parameter can take the following values:

Layer id Type  Description
o3_conc Pollutant layer Ozone concentration (µg/m³) layer
no2_conc Pollutant layer Nitrogen dioxide concentration (µg/m³) layer
pm25_conc Pollutant layer Particulate matter 2.5 concentration (µg/m³) layer
pm10_conc Pollutant layer Particulate matter 10 concentration (µg/m³) layer
meersens Index layer Meersens proprietary Air Quality Index layer
cn_aqi Index layer China MEP Air Quality Index layer
fra_aqi Index layer France ATMO Air Quality Index layer
usa_aqi Index layer US Environmental Protection Agency (EPA) Air Quality Index layer

Client access

As Meersens follows the OGC and particularly WMS, all the front client library can access the data easily, thus JS clients such as OpenLayers, Leaflet, Mapbox and so on support WMS protocol.

Air quality geographical aggregation

import requests

requests.get("https://api.meersens.com/environment/public/air/current/aggregate", headers={
  'apikey': 'your_api_key'
}, params={
  code: 69006,
  location_type: 'postal_code',
  iso2_code: 'FR'
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/air/current/aggregate?code=69006&location_type=postal_code&iso2_code=fr" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/air/current/aggregate",{
  params: { 
    code: 69006,
    location_type: 'postal_code',
    iso2_code: 'FR'
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "datetime": "2023-04-07T14:00:00.000Z",
    "indexes": {
        "mean": {
            "index_type": "meersens",
            "index_name": "MAQI",
            "qualification": "Moderate",
            "icon": null,
            "color": "#adc704",
            "description": "Air quality level will present a risk for health for an exposure time superior to several days",
            "value": 40.95,
            "main_pollutants": [
                "o3"
            ]
        },
        "min": {
            "index_type": "meersens",
            "index_name": "MAQI",
            "qualification": "Moderate",
            "icon": null,
            "color": "#adc704",
            "description": "Air quality level will present a risk for health for an exposure time superior to several days",
            "value": 40.05,
            "main_pollutants": [
                "o3"
            ]
        },
        "max": {
            "index_type": "meersens",
            "index_name": "MAQI",
            "qualification": "Moderate",
            "icon": null,
            "color": "#adc704",
            "description": "Air quality level will present a risk for health for an exposure time superior to several days",
            "value": 47.73,
            "main_pollutants": [
                "no2"
            ]
        }
    },
    "pollutants": {
        "co": {
            "shortcode": "CO",
            "name": "Carbon monoxide",
            "unit": "µg/m³",
            "found": true,
            "values": {
                "mean": 135,
                "min": 133.4,
                "max": 136.4
            },
            "confidence": 5,
            "indexes": {
                "mean": {
                    "index_type": "meersens",
                    "index_name": "MAQI",
                    "qualification": "Good",
                    "icon": null,
                    "color": "#05b3a4",
                    "description": "Air quality level won’t present a risk for health for an exposure time superior to decades",
                    "value": 0.33
                },
                "min": {
                    "index_type": "meersens",
                    "index_name": "MAQI",
                    "qualification": "Good",
                    "icon": null,
                    "color": "#05b3a4",
                    "description": "Air quality level won’t present a risk for health for an exposure time superior to decades",
                    "value": 0.32
                },
                "max": {
                    "index_type": "meersens",
                    "index_name": "MAQI",
                    "qualification": "Good",
                    "icon": null,
                    "color": "#05b3a4",
                    "description": "Air quality level won’t present a risk for health for an exposure time superior to decades",
                    "value": 0.33
                }
            }
        },
        "no2": {...},
        "o3": {...},
        "pm10": {...},
        "pm25": {...},
        "so2": {...}
      }
    }
}

Returns current information about air quality conditions for a given postal code. The returned results give an overview of the minimum, maximum and average values found for each pollutant, on the area covered by the specified postal code. Please note that this is only available for french postal codes so far.

Path

GET https://api.meersens.com/environment/public/air/current/aggregate

Query Parameters

Parameter Type   Description Required
code number The postal code of the geographical area to aggregate. true
location_type string The type of the location to apply the aggregation on (postal_code). true
iso2_code string The ISO 3166-1 alpha-2 code of the country of the requested postal code. true
health_recommendations boolean Indicates whether health recommendations should be retrieved for this air quality levels or not. false
(default:false)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found.
datetime string ISO_8601 UTC datetime indicating the time the data refers to.
indexes  object Dictionary of the min, max and mean air quality index objects.
indexes.[statistic].index_type  string Unique identifier of the returned air quality index.
indexes.[statistic].index_name  string Name of the returned air quality index.
indexes.[statistic].qualification  string Air quality index textual representation.
indexes.[statistic].description  string Air quality index textual assessment.
indexes.[statistic].icon  string Air quality level associated icon (if any, otherwise null).
indexes.[statistic].color  string Air quality level hexadecimal color code.
indexes.[statistic].value  number Air quality level value (for numeric indexes only, otherwise null).
indexes.[statistic].main_pollutants  array Array of main pollutants identifiers.
pollutants  object Dictionary of available pollutants at the requested point.
pollutants.shortcode  string Pollutant textual shortcode.
pollutants.name  string Pollutant full name.
pollutants.unit  string Unit in which the pollutant value is returned.
pollutants.found  boolean Whether the pollutant value has been found.
pollutants.values  object Dictionary of the pollutant values statistics in specified unit.
pollutants.values.min  number Minimum value of the pollutant in specified unit on the requested area.
pollutants.values.max  number Maximum value of the pollutant in specified unit on the requested area.
pollutants.values.mean  number Average value of the pollutant in specified unit on the requested area.
pollutants.confidence  number Pollutant value confidence.
pollutants.indexes  object Dictionary of the pollutant specific index information statistics over the requested area.
pollutants.indexes.[statistic].index_type  string Unique identifier of the returned air quality index.
pollutants.indexes.[statistic].index_name  string Name of the returned air quality index.
pollutants.indexes.[statistic].qualification  string Air quality index textual representation.
pollutants.indexes.[statistic].description  string Air quality index textual assessment.
pollutants.indexes.[statistic].icon  string Pollutant level associated icon (if any, otherwise null).
pollutants.indexes.[statistic].color  string Pollutant level hexadecimal color code.
pollutants.indexes.[statistic].value  number Pollutant level index value (for numeric indexes only, otherwise null).
health_recommendations object Dictionary of health recommendations computed for various population categories, including:
-all : general population
-family : populations with childrens
-sport : sports populations
-pregnancy : pregnant populations
-elderly : elderly populations
-respiratory : populations with respiratory diseases
-cardiovascular : populations with cardiovascular diseases
The health recommendations are computed using the mean values of the current conditions over the specified area.

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

Air quality history geographical aggregation

import requests

requests.get("https://api.meersens.com/environment/public/air/history/aggregate", headers={
  'apikey': 'your_api_key'
}, params={
  code: 69006,
  location_type: 'postal_code',
  iso2_code: 'FR',
  duration: 'hour',
  page: 1,
  from: '2023-02-01T00:00:00Z',
  to: '2023-02-02T00:00:00Z'
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/air/history/aggregate?code=69006&location_type=postal_code&iso2_code=fr&duration=hour&page=1&from=2023-02-01T00:00:00Z&to=2023-02-02T00:00:00Z" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/air/history/aggregate",{
  params: { 
    code: 69006,
    location_type: 'postal_code',
    iso2_code: 'FR',
    duration: 'hour',
    page: 1,
    from: '2023-02-01T00:00:00Z',
    to: '2023-02-02T00:00:00Z'
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "values": [
        {
            "datetime": "2021-11-07T22:00:00.000Z",
            "pollutants": {    
                "no2": {
                  {
                    "shortcode": "NO2",
                    "name": "Nitrogen dioxide",
                    "unit": "µg/m³",
                    "found": true,
                    "values": {
                        "mean": 12.2,
                        "min": 11.5,
                        "max": 18.6
                    },
                    "confidence": 5,
                    "indexes": {
                        "mean": {
                            "index_type": "meersens",
                            "index_name": "MAQI",
                            "qualification": "Moderate",
                            "icon": null,
                            "color": "#adc704",
                            "description": "Air quality level will present a risk for health for an exposure time superior to several days",
                            "value": 35.49
                        },
                        "min": {
                            "index_type": "meersens",
                            "index_name": "MAQI",
                            "qualification": "Moderate",
                            "icon": null,
                            "color": "#adc704",
                            "description": "Air quality level will present a risk for health for an exposure time superior to several days",
                            "value": 34.7
                        },
                        "max": {
                            "index_type": "meersens",
                            "index_name": "MAQI",
                            "qualification": "Moderate",
                            "icon": null,
                            "color": "#adc704",
                            "description": "Air quality level will present a risk for health for an exposure time superior to several days",
                            "value": 42.75
                        }
                    }
                  }
                },
                "co": {...},
                "o3": {...},
                "pm10": {...},
                "pm25": {...},
                "so2": {...}
            },
            "indexes": {
                "mean": {
                    "index_type": "meersens",
                    "index_name": "MAQI",
                    "qualification": "Moderate",
                    "icon": null,
                    "color": "#adc704",
                    "description": "Air quality level will present a risk for health for an exposure time superior to several days",
                    "value": 37.93,
                    "main_pollutants": [
                        "pm25"
                    ]
                },
                "min": {
                    "index_type": "meersens",
                    "index_name": "MAQI",
                    "qualification": "Moderate",
                    "icon": null,
                    "color": "#adc704",
                    "description": "Air quality level will present a risk for health for an exposure time superior to several days",
                    "value": 37.59,
                    "main_pollutants": [
                        "pm25"
                    ]
                },
                "max": {
                    "index_type": "meersens",
                    "index_name": "MAQI",
                    "qualification": "Moderate",
                    "icon": null,
                    "color": "#adc704",
                    "description": "Air quality level will present a risk for health for an exposure time superior to several days",
                    "value": 42.41,
                    "main_pollutants": [
                        "no2"
                    ]
                }
            },
            "found": true
        },
        {...}
    ],
    "page": {
        "totalElements": 24,
        "totalPages": 4,
        "pageNumber": 1,
        "size": 6
    }
}

Returns hourly or daily history air quality data for a given area or location. For each time point included in the requested timeframe, the minimum, maximum and average pollutants concentrations will be retrieved (if found), along with the computed min, max and mean air quality indexes. Hourly aggregation is only available for a period up to six months ago, and for postal codes. Please note that this is only available for french postal codes so far.

Path

GET https://api.meersens.com/environment/public/air/history/aggregate

Query Parameters

Parameter Type   Description Required
location_type string The type of requested location ("point" or "postal_code"). true
code number The postal code of the geographical area to aggregate. Required if location_type = "postal_code" false
iso2_code string The ISO 3166-1 alpha-2 code of the country of the requested postal code. Required if location_type = "postal_code" false
lat number The latitude of the point to request daily values for. Required if location_type = "point" false
lng number The longitude of the point to request daily values for. Required if location_type = "point" false
duration string The duration of the temporal aggregation ("day" or "hour") false (default: "hour")
from string ISO_8601 UTC datetime (including timezone) that indicates the starting date of the history timeframe data. false
(default:24hours ago)
to string ISO_8601 UTC datetime (including timezone) that indicates the ending date of the history timeframe data. false
(default:beginning of current hour)
page number The number of the page to return among the pages of results. false (default: 0)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found.
values array Array of hourly or daily air quality min, max and mean values.
values.datetime string ISO_8601 UTC datetime indicating the time the data refers to for this hourly or daily entry.
values.indexes  object Dictionary of the min, max and mean air quality index objects.
values.indexes.[statistic].index_type  string Unique identifier of the returned air quality index.
values.indexes.[statistic].index_name  string Name of the returned air quality index.
values.indexes.[statistic].qualification  string Air quality index textual representation.
values.indexes.[statistic].description  string Air quality index textual assessment.
values.indexes.[statistic].icon  string Air quality level associated icon (if any, otherwise null).
values.indexes.[statistic].color  string Air quality level hexadecimal color code.
values.indexes.[statistic].value  number Air quality level value (for numeric indexes only, otherwise null).
values.indexes.[statistic].main_pollutants  array Array of main pollutants identifiers.
values.pollutants  object Dictionary of available pollutants at the requested point.
values.pollutants.shortcode  string Pollutant textual shortcode.
values.pollutants.name  string Pollutant full name.
values.pollutants.unit  string Unit in which the pollutant value is returned.
values.pollutants.found  boolean Whether the pollutant value has been found.
values.pollutants.values  object Dictionary of the pollutant values statistics in specified unit.
values.pollutants.values.min  number Minimum value of the pollutant in specified unit on the requested area.
values.pollutants.values.max  number Maximum value of the pollutant in specified unit on the requested area.
values.pollutants.values.mean  number Average value of the pollutant in specified unit on the requested area.
values.pollutants.confidence  number Pollutant value confidence.
values.pollutants.indexes  object Dictionary of the pollutant specific index information statistics over the requested area.
values.pollutants.indexes.[statistic].index_type  string Unique identifier of the returned air quality index.
values.pollutants.indexes.[statistic].index_name  string Name of the returned air quality index.
values.pollutants.indexes.[statistic].qualification  string Air quality index textual representation.
values.pollutants.indexes.[statistic].description  string Air quality index textual assessment.
values.pollutants.indexes.[statistic].icon  string Pollutant level associated icon (if any, otherwise null).
values.pollutants.indexes.[statistic].color  string Pollutant level hexadecimal color code.
values.pollutants.indexes.[statistic].value  number Pollutant level index value (for numeric indexes only, otherwise null).
page object Object containing information about the pagination of the response.
page.totalElements number The total amount of air quality values.
page.totalPages number The amount of pages of air quality values.
page.pageNumber number The number of the page currently returned.
page.size number The amount of air quality values returned per page.

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

Air quality forecast geographical aggregation

Returns hourly forecast air quality data at a given location. For each hour included in the requested timeframe, the minimum, maximum and average pollutants concentrations will be retrieved (if found), along with the computed min, max and mean air quality indexes.The maximum timeframe allowed to be requested is 96 hours, meaning 4 days. Please refer to the above page for details about the query input and output. Please note that daily aggregation is not supported for forecast data. Please note that this is only available for french postal codes so far.

Path

GET https://api.meersens.com/environment/public/air/forecast/aggregate

Noise

The noise API lets you request noise levels for a specific location. Retrieved information includes average noise levels, data confidence, comparison with W.H.O applicable standards & norms and generic health recommendations.
As the computing of hourly noise levels is not yet possible, this API will retrieve for a specific location average noise levels, based on four different periods of time:

Noise indexes

In order to let you easily interpretate environmental data, each one is associated to an environmental index. This index is designed to represent a human-readable assessment of a given environmental quality, simplifying the readings of raw pollutants concentrations and emphasizing eventual country specificities given pollutants levels interpretation.

For Noise, Meersens currently supports the following indexes:

ID Name  Numeric Description Pollutants
meersens Meersens Noise Index true Meersens proprietary Noise Index noise

Noise current conditions

import requests

requests.get("https://api.meersens.com/environment/public/noise/current", headers={
  'apikey': 'your_api_key'
}, params={
  lat: 1.234,
  lng: 5.678
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/noise/current?lat=1.234&lng=5.678" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/noise/current",{
  params: { 
    lat: 1.234,
    lng: 5.678
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "datetime": "2021-11-08T21:00:00.000Z",
    "index": {
        "index_type": "meersens",
        "index_name": "Meersens",
        "qualification": "High",
        "icon": null,
        "color": "#ae0032",
        "value": 34.13,
        "main_pollutants": [
            "noise"
        ]
    },
    "pollutants": {
        "noise": {
            "shortcode": "Noise",
            "name": "Noise",
            "unit": "dB",
            "found": true,
            "value": 75,
            "confidence": 4.5,
            "index": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "High",
                "icon": null,
                "color": "#ae0032",
                "description": "Sound intensity of a washing machine. Noisy.",
                "value": 14.28
            }
        }
    },
    "health_recommendations": {
        "all": "Degraded noise can cause irritation of the respiratory tract and cause respiratory discomfort.",
        "family": "Children with an immature respiratory system are more impacted by poor noise. Outdoor activities can be maintained as long as there is no respiratory or cardiac discomfort.",
        "sport": "Physical activities cause an increase in respiratory rate which leads to increased exposure to pollutants and potentially to symptoms resulting from them.",
        "pregnancy": "Exposure to pollutants can affect the fetus and pregnancy (lower birth weight, preterm delivery ...)",
        "respiratory": "Air pollution can worsen respiratory pathologies such as asthma, COPD, chronic bronchitis ...",
        "elderly": "With age, the respiratory system can become weakened and pollution can exacerbate respiratory problems",
        "cardiovascular": "Air pollution has been implicated in the development or aggravation of cardiovascular disease"
    }
}

Returns current information about noise conditions for a specific location.

Path

GET https://api.meersens.com/environment/public/noise/current

Query Parameters

Parameter Type   Description Required
lat number Latitude of the location to compute noise conditions at. In WGS84 format. true
lng number Longitude of the location to compute noise conditions at. In WGS84 format. true
index_type string Unique identifier of the desired output noise index. Use reserved keyword local to get the locally applicable index at the point you're requesting data. false
(default:meersens)
health_recommendations boolean Indicates whether health recommendations should be retrieved for this noise levels or not. false
(default:false)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found.
datetime string ISO_8601 UTC datetime indicating the time the data refers to.
index  object Noise index object.
index.index_type  string Unique identifier of the returned noise index.
index.index_name  string Name of the returned noise index.
index.qualification  string Noise index textual representation.
index.description  string Noise index textual assessment.
index.icon  string Noise level associated icon (if any, otherwise null).
index.color  string Noise level hexadecimal color code.
index.value  number Noise level value (for numeric indexes only, otherwise null).
index.main_pollutants  array Array of main pollutants identifiers.
pollutants  object Dictionary of available pollutants at the requested point.
pollutants.shortcode  string Pollutant textual shortcode.
pollutants.name  string Pollutant full name.
pollutants.unit  string Unit in which the pollutant value is returned.
pollutants.found  boolean Whether the pollutant value has been found.
pollutants.value  string Textual range value of the pollutant in specified unit.
pollutants.avg_value  number Numeric averaged value of the pollutant in specified unit.
pollutants.confidence  number Pollutant value confidence.
pollutants.index  object Pollutant specific index information
pollutants.index.index_type  string Unique identifier of the returned noise index.
pollutants.index.index_name  string Name of the returned noise index.
pollutants.index.qualification  string Noise index textual representation.
pollutants.index.description  string Noise index textual assessment.
pollutants.index.icon  string Pollutant level associated icon (if any, otherwise null).
pollutants.index.color  string Pollutant level hexadecimal color code.
pollutants.index.value  number Pollutant level index value (for numeric indexes only, otherwise null).
health_recommendations object Dictionary of health recommendations for various population categories, including:
-all : general population
-family : populations with childrens
-sport : sports populations
-pregnancy : pregnant populations
-elderly : elderly populations
-respiratory : populations with respiratory diseases
-cardiovascular : populations with cardiovascular diseases

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

Pollens

The pollen API lets you request pollen data for a specific location. Retrieved information includes pollen concentration levels, data confidence, comparison with W.H.O applicable standards & norms and generic health recommendations.
Major pollen species are available, including:

Pollen indexes

In order to let you easily interpretate environmental data, each one is associated to an environmental index. This index is designed to represent a human-readable assessment of a given environmental quality, simplifying the readings of raw pollutants concentrations and emphasizing eventual country specificities given pollutants levels interpretation.

For Pollens, Meersens currently supports the following indexes:

ID Name  Numeric Description Pollutants
meersens Meersens Pollen Index true Meersens proprietary Pollen Index alder, ash, aspen, beech, birch, broadleaved, cedar, chestnut, conifers, cypress, douglas, elm, eucalyptus, fern, fir, grasses, hemlock, katsura, knotweed, larch, maple, mugwort, oak, olive, pine, prunus, ragweed, rowan, spruce, walnut, willow
meersens_gpi Meersens Grasses Pollen Index true Meersens proprietary Grasses Pollen Index grasses
meersens_tpi Meersens Trees Pollen Index true Meersens proprietary Trees Pollen Index alder, ash, aspen, beech, birch, broadleaved, cedar, chestnut, conifers, cypress, douglas, elm, eucalyptus, fern, fir, grasses, hemlock, katsura, larch, maple, oak, olive, pine, prunus, rowan, spruce, walnut, willow"
meersens_wpi Meersens Weeds Pollen Index true Meersens proprietary Weeds Pollen Index knotweed, mugwort, ragweed

Pollen current conditions

import requests

requests.get("https://api.meersens.com/environment/public/pollen/current", headers={
  'apikey': 'your_api_key'
}, params={
  lat: 1.234,
  lng: 5.678
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/pollen/current?lat=1.234&lng=5.678" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/pollen/current",{
  params: { 
    lat: 1.234,
    lng: 5.678
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "datetime": "2021-11-08T21:00:00.000Z",
    "index": {
        "index_type": "meersens",
        "index_name": "Meersens",
        "qualification": "Degraded",
        "icon": null,
        "color": "#adc704",
        "value": 34.13,
        "main_pollutants": [
            "ragweed"
        ]
    },
    "pollutants": {
        "ragweed": {
            "shortcode": "Rag.",
            "name": "Ragweed",
            "unit": "grains/m³",
            "found": true,
            "value": 4.1,
            "confidence": 4.5,
            "index": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "Good",
                "icon": null,
                "color": "#05b3a4",
                "description": "Ragweed pollen has a very high allergenic power, the main cause of hay fever. Low risk of allergy to this concentration",
                "value": 14.28
            }
        },
        "birch": {...},
        "olive": {...},
        "alder": {...},
        "mugwort": {...},
        "grasses": {...}
    },
    "health_recommendations": {
        "all": "Degraded pollen can cause irritation of the respiratory tract and cause respiratory discomfort.",
        "family": "Children with an immature respiratory system are more impacted by poor pollen. Outdoor activities can be maintained as long as there is no respiratory or cardiac discomfort.",
        "sport": "Physical activities cause an increase in respiratory rate which leads to increased exposure to pollutants and potentially to symptoms resulting from them.",
        "pregnancy": "Exposure to pollutants can affect the fetus and pregnancy (lower birth weight, preterm delivery ...)",
        "respiratory": "Air pollution can worsen respiratory pathologies such as asthma, COPD, chronic bronchitis ...",
        "elderly": "With age, the respiratory system can become weakened and pollution can exacerbate respiratory problems",
        "cardiovascular": "Air pollution has been implicated in the development or aggravation of cardiovascular disease"
    }
}

Returns current information about pollen conditions for a specific location.

Path

GET https://api.meersens.com/environment/public/pollen/current

Query Parameters

Parameter Type   Description Required
lat number Latitude of the location to compute pollen conditions at. In WGS84 format. true
lng number Longitude of the location to compute pollen conditions at. In WGS84 format. true
index_type string Unique identifier of the desired output pollen index. Use reserved keyword local to get the locally applicable index at the point you're requesting data. false
(default:meersens)
health_recommendations boolean Indicates whether health recommendations should be retrieved for this pollen levels or not. false
(default:false)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found.
datetime string ISO_8601 UTC datetime indicating the time the data refers to.
index  object Pollen index object.
index.index_type  string Unique identifier of the returned pollen index.
index.index_name  string Name of the returned pollen index.
index.qualification  string Pollen index textual representation.
index.description  string Pollen index textual assessment.
index.icon  string Pollen level associated icon (if any, otherwise null).
index.color  string Pollen level hexadecimal color code.
index.value  number Pollen level value (for numeric indexes only, otherwise null).
index.main_pollutants  array Array of main pollutants identifiers.
pollutants  object Dictionary of available pollutants at the requested point.
pollutants.shortcode  string Pollutant textual shortcode.
pollutants.name  string Pollutant full name.
pollutants.unit  string Unit in which the pollutant value is returned.
pollutants.found  boolean Whether the pollutant value has been found.
pollutants.value  number Value of the pollutant in specified unit.
pollutants.confidence  number Pollutant value confidence.
pollutants.index  object Pollutant specific index information
pollutants.index.index_type  string Unique identifier of the returned pollen index.
pollutants.index.index_name  string Name of the returned pollen index.
pollutants.index.qualification  string Pollen index textual representation.
pollutants.index.description  string Pollen index textual assessment.
pollutants.index.icon  string Pollutant level associated icon (if any, otherwise null).
pollutants.index.color  string Pollutant level hexadecimal color code.
pollutants.index.value  number Pollutant level index value (for numeric indexes only, otherwise null).
health_recommendations object Dictionary of health recommendations for various population categories, including:
-all : general population
-family : populations with childrens
-sport : sports populations
-pregnancy : pregnant populations
-elderly : elderly populations
-respiratory : populations with respiratory diseases
-cardiovascular : populations with cardiovascular diseases

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

Pollen history

import requests

requests.get("https://api.meersens.com/environment/public/pollen/history", headers={
  'apikey': 'your_api_key'
}, params={
  lat: 1.234,
  lng: 5.678,
  from: '2021-01-01T00:00:00Z',
  to: '2021-01-02T00:00:00Z',
  page: 0
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/pollen/history?lat=1.234&lng=5.678&from=2021-01-01T00:00:00Z&to=2021-01-02T00:00:00Z&page=0" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/pollen/forecast",{
  params: { 
    lat: 1.234,
    lng: 5.678,
    from: '2021-01-01T00:00:00Z',
    to: '2021-01-02T00:00:00Z',
    page: 0
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "values": [
        {
            "datetime": "2021-11-07T22:00:00.000Z",
            "pollutants": {    
                "ragweed": {
                    "shortcode": "Rag.",
                    "name": "Ragweed",
                    "unit": "grains/m³",
                    "found": true,
                    "value": 4.1,
                    "confidence": 4.5,
                    "index": {
                        "index_type": "meersens",
                        "index_name": "Meersens",
                        "qualification": "Good",
                        "icon": null,
                        "color": "#05b3a4",
                        "description": "Ragweed pollen has a very high allergenic power, the main cause of hay fever. Low risk of allergy to this concentration",
                        "value": 14.28
                    }
                },
                "birch": {...},
                "olive": {...},
                "alder": {...},
                "mugwort": {...},
                "grasses": {...}
            },
            "index": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "Correct",
                "icon": null,
                "color": "#44b001",
                "value": 32.62,
                "main_pollutants": [
                    "ragweed"
                ]
            },
            "found": true
        },
        {...}
    ],
    "page": {
      "totalElements": 24,
      "totalPages": 4,
      "pageNumber": 0,
      "size": 6
    }
}

Returns paginated hourly history pollen data at a given location. For each hour included in the requested timeframe, the pollens concentrations will be retrieved (if found), along with the computed index. Each returned page will contain up to 6 time points entries.

Path

GET https://api.meersens.com/environment/public/pollen/history

Query Parameters

Parameter Type   Description Required
lat number Latitude of the location to compute pollen conditions at. In WGS84 format. true
lng number Longitude of the location to compute pollen conditions at. In WGS84 format. true
from string ISO_8601 UTC datetime (including timezone) that indicates the starting date of the history timeframe data. false
(default:24hours ago)
to string ISO_8601 UTC datetime (including timezone) that indicates the ending date of the history timeframe data. false
(default:beginning of current hour)
index_type string Unique identifier of the desired output pollen index. Use reserved keyword local to get the locally applicable index at the point you're requesting data. false
(default:meersens)
page number The number of the page to return among the pages of results. false (default: 0)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found over the period.
values array Array of hourly pollen values.
values.datetime string ISO_8601 UTC datetime indicating the time the data refers to for this hourly entry.
values.index  object Pollen index object for this hourly entry.
values.index.index_type  string Unique identifier of the returned pollen index.
values.index.index_name  string Name of the returned pollen index.
values.index.qualification  string Pollen index textual representation.
values.index.description  string Pollen index textual assessment.
values.index.icon  string Pollen level associated icon (if any, otherwise null).
values.index.color  string Pollen level hexadecimal color code.
values.index.value  number Pollen level value (for numeric indexes only, otherwise null).
values.index.main_pollutants  array Array of main pollutants identifiers.
values.pollutants  object Dictionary of available pollutants at the requested point for this hourly entry.
values.pollutants.shortcode  string Pollutant textual shortcode.
values.pollutants.name  string Pollutant full name.
values.pollutants.unit  string Unit in which the pollutant value is returned.
values.pollutants.found  boolean Whether the pollutant value has been found.
values.pollutants.value  number Value of the pollutant in specified unit.
values.pollutants.confidence  number Pollutant value confidence.
values.pollutants.index  object Pollutant specific index information
values.pollutants.index.index_type  string Unique identifier of the returned pollen index.
values.pollutants.index.index_name  string Name of the returned pollen index.
values.pollutants.index.qualification  string Pollen index textual representation.
values.pollutants.index.description  string Pollen index textual assessment.
values.pollutants.index.icon  string Pollutant level associated icon (if any, otherwise null).
values.pollutants.index.color  string Pollutant level hexadecimal color code.
values.pollutants.index.value  number Pollutant level index value (for numeric indexes only, otherwise null).
page object Object containing information about the pagination of the response.
page.totalElements number The total amount of pollen values.
page.totalPages number The amount of pages of pollen values.
page.pageNumber number The number of the page currently returned.
page.size number The amount of pollen values returned per page.

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

Pollen forecast

import requests

requests.get("https://api.meersens.com/environment/public/pollen/forecast", headers={
  'apikey': 'your_api_key'
}, params={
  lat: 1.234,
  lng: 5.678,
  from: '2021-01-01T00:00:00Z',
  to: '2021-01-02T00:00:00Z',
  page: 0
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/pollen/forecast?lat=1.234&lng=5.678&from=2021-01-01T00:00:00Z&to=2021-01-02T00:00:00Z&page=0" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/pollen/forecast",{
  params: { 
    lat: 1.234,
    lng: 5.678,
    from: '2021-01-01T00:00:00Z',
    to: '2021-01-02T00:00:00Z',
    page: 0
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "values": [
        {
            "datetime": "2021-11-07T22:00:00.000Z",
            "pollutants": {    
                "ragweed": {
                    "shortcode": "Rag.",
                    "name": "Ragweed",
                    "unit": "grains/m³",
                    "found": true,
                    "value": 4.1,
                    "confidence": 4.5,
                    "index": {
                        "index_type": "meersens",
                        "index_name": "Meersens",
                        "qualification": "Good",
                        "icon": null,
                        "color": "#05b3a4",
                        "description": "Ragweed pollen has a very high allergenic power, the main cause of hay fever. Low risk of allergy to this concentration",
                        "value": 14.28
                    }
                },
                "birch": {...},
                "olive": {...},
                "alder": {...},
                "mugwort": {...},
                "grasses": {...}
            },
            "index": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "Correct",
                "icon": null,
                "color": "#44b001",
                "value": 32.62,
                "main_pollutants": [
                    "o3"
                ]
            },
            "found": true
        },
        {...}
    ],
    "page": {
        "totalElements": 24,
        "totalPages": 4,
        "pageNumber": 0,
        "size": 6
    }
}

Returns paginated hourly forecast pollen data at a given location. For each hour included in the requested timeframe, the pollens concentrations will be retrieved (if found), along with the computed index. The maximum timeframe allowed to be requested is 96 hours, meaning 4 days. Each returned page will contain up to 6 time points entries.

Path

GET https://api.meersens.com/environment/public/pollen/forecast

Query Parameters

Parameter Type   Description Required
lat number Latitude of the location to compute pollen conditions at. In WGS84 format. true
lng number Longitude of the location to compute pollen conditions at. In WGS84 format. true
from string ISO_8601 UTC datetime (including timezone) that indicates the starting date of the forecast timeframe data. false
(default:24hours ago)
to string ISO_8601 UTC datetime (including timezone) that indicates the ending date of the forecast timeframe data. false
(default:beginning of current hour)
index_type string Unique identifier of the desired output pollen index. Use reserved keyword local to get the locally applicable index at the point you're requesting data. false
(default:meersens)
page number The number of the page to return among the pages of results. false (default: 0)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found over the period.
values array Array of hourly pollen values.
values.datetime string ISO_8601 UTC datetime indicating the time the data refers to for this hourly entry.
values.index  object Pollen index object for this hourly entry.
values.index.index_type  string Unique identifier of the returned pollen index.
values.index.index_name  string Name of the returned pollen index.
values.index.qualification  string Pollen index textual representation.
values.index.description  string Pollen index textual assessment.
values.index.icon  string Pollen level associated icon (if any, otherwise null).
values.index.color  string Pollen level hexadecimal color code.
values.index.value  number Pollen level value (for numeric indexes only, otherwise null).
values.index.main_pollutants  array Array of main pollutants identifiers.
values.pollutants  object Dictionary of available pollutants at the requested point for this hourly entry.
values.pollutants.shortcode  string Pollutant textual shortcode.
values.pollutants.name  string Pollutant full name.
values.pollutants.unit  string Unit in which the pollutant value is returned.
values.pollutants.found  boolean Whether the pollutant value has been found.
values.pollutants.value  number Value of the pollutant in specified unit.
values.pollutants.confidence  number Pollutant value confidence.
values.pollutants.index  object Pollutant specific index information
values.pollutants.index.index_type  string Unique identifier of the returned pollen index.
values.pollutants.index.index_name  string Name of the returned pollen index.
values.pollutants.index.qualification  string Pollen index textual representation.
values.pollutants.index.description  string Pollen index textual assessment.
values.pollutants.index.icon  string Pollutant level associated icon (if any, otherwise null).
values.pollutants.index.color  string Pollutant level hexadecimal color code.
values.pollutants.index.value  number Pollutant level index value (for numeric indexes only, otherwise null).
page object Object containing information about the pagination of the response.
page.totalElements number The total amount of pollen values.
page.totalPages number The amount of pages of pollen values.
page.pageNumber number The number of the page currently returned.
page.size number The amount of pollen values returned per page.

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

Pollen geographical aggregation

import requests

requests.get("https://api.meersens.com/environment/public/pollen/current/aggregate", headers={
  'apikey': 'your_api_key'
}, params={
  code: 69006,
  location_type: 'postal_code',
  iso2_code: 'FR'
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/pollen/current/aggregate?code=69006&location_type=postal_code&iso2_code=fr" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/pollen/current/aggregate",{
  params: { 
    code: 69006,
    location_type: 'postal_code',
    iso2_code: 'FR'
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
  "found": true,
  "datetime": "2023-04-07T15:00:00.000Z",
  "indexes": {
      "mean": {
          "index_type": "meersens",
          "index_name": "Meersens",
          "qualification": "Moderate",
          "icon": null,
          "color": "#adc704",
          "description": "Moderate allergy risk",
          "value": 40.18,
          "main_pollutants": [
              "birch_tree"
          ]
      },
      "min": {
          "index_type": "meersens",
          "index_name": "Meersens",
          "qualification": "Moderate",
          "icon": null,
          "color": "#adc704",
          "description": "Moderate allergy risk",
          "value": 38.25,
          "main_pollutants": [
              "birch_tree"
          ]
      },
      "max": {
          "index_type": "meersens",
          "index_name": "Meersens",
          "qualification": "Moderate",
          "icon": null,
          "color": "#adc704",
          "description": "Moderate allergy risk",
          "value": 45.73,
          "main_pollutants": [
              "birch_tree"
          ]
      }
  },
  "birch_tree": {
    "shortcode": "Bir.",
    "name": "Birch tree",
    "unit": "grains/m³",
    "found": true,
    "values": {
        "mean": 46.66,
        "min": 38.18,
        "max": 71.18
    },
    "confidence": 5,
    "indexes": {
        "mean": {
            "index_type": "meersens",
            "index_name": "Meersens",
            "qualification": "Moderate",
            "icon": null,
            "color": "#adc704",
            "description": "Moderate allergy risk",
            "value": 40.18
        },
        "min": {
            "index_type": "meersens",
            "index_name": "Meersens",
            "qualification": "Moderate",
            "icon": null,
            "color": "#adc704",
            "description": "Moderate allergy risk",
            "value": 38.25
        },
        "max": {
            "index_type": "meersens",
            "index_name": "Meersens",
            "qualification": "Moderate",
            "icon": null,
            "color": "#adc704",
            "description": "Moderate allergy risk",
            "value": 45.73
        }
    }
  },
  "olive_tree": {...},
  "alder_tree": {...},
  "mugwort": {...},
  "grasses": {...}
}

Returns current information about pollen conditions for a given postal code. The returned results give an overview of the minimum, maximum and average values found for each pollen type, on the area covered by the specified postal code. Please note that this is only available for french postal codes so far.

Path

GET https://api.meersens.com/environment/public/pollen/current/aggregate

Query Parameters

Parameter Type   Description Required
code number The postal code of the geographical area to aggregate. true
location_type string The type of the location to apply the aggregation on. true
iso2_code string The ISO 3166-1 alpha-2 code of the country of the requested postal code. true
health_recommendations boolean Indicates whether health recommendations should be retrieved for this pollens levels or not. false
(default:false)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found.
datetime string ISO_8601 UTC datetime indicating the time the data refers to.
indexes  object Dictionary of the min, max and mean pollen index objects.
indexes.[statistic].index_type  string Unique identifier of the returned pollen index.
indexes.[statistic].index_name  string Name of the returned pollen index.
indexes.[statistic].qualification  string Pollen index textual representation.
indexes.[statistic].description  string Pollen index textual assessment.
indexes.[statistic].icon  string Pollen level associated icon (if any, otherwise null).
indexes.[statistic].color  string Pollen level hexadecimal color code.
indexes.[statistic].value  number Pollen level value (for numeric indexes only, otherwise null).
indexes.[statistic].main_pollutants  array Array of main pollutants identifiers.
pollutants  object Dictionary of available pollutants at the requested point.
pollutants.shortcode  string Pollutant textual shortcode.
pollutants.name  string Pollutant full name.
pollutants.unit  string Unit in which the pollutant value is returned.
pollutants.found  boolean Whether the pollutant value has been found.
pollutants.values  object Dictionary of the pollutant values statistics in specified unit.
pollutants.values.min  number Minimum value of the pollutant in specified unit on the requested area.
pollutants.values.max  number Maximum value of the pollutant in specified unit on the requested area.
pollutants.values.mean  number Average value of the pollutant in specified unit on the requested area.
pollutants.confidence  number Pollutant value confidence.
pollutants.indexes  object Dictionary of the pollutant specific index information statistics over the requested area.
pollutants.indexes.[statistic].index_type  string Unique identifier of the returned pollen index.
pollutants.indexes.[statistic].index_name  string Name of the returned pollen index.
pollutants.indexes.[statistic].qualification  string Pollen index textual representation.
pollutants.indexes.[statistic].description  string Pollen index textual assessment.
pollutants.indexes.[statistic].icon  string Pollutant level associated icon (if any, otherwise null).
pollutants.indexes.[statistic].color  string Pollutant level hexadecimal color code.
pollutants.indexes.[statistic].value  number Pollutant level index value (for numeric indexes only, otherwise null).
health_recommendations object Dictionary of health recommendations for various population categories, including:
-all : general population
-family : populations with childrens
-sport : sports populations
-pregnancy : pregnant populations
-elderly : elderly populations
-respiratory : populations with respiratory diseases
-cardiovascular : populations with cardiovascular diseases
The health recommendations are computed using the mean values of the current conditions over the specified area.

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

Pollen history geographical aggregation

import requests

requests.get("https://api.meersens.com/environment/public/pollen/history/aggregate", headers={
  'apikey': 'your_api_key'
}, params={
  code: 69006,
  location_type: 'postal_code',
  iso2_code: 'FR',
  page: 1,
  from: '2023-02-01T00:00:00Z',
  to: '2023-02-02T00:00:00Z'
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/pollen/history/aggregate?code=69006&page=1&location_type=postal_code&iso2_code=fr&from=2023-02-01T00:00:00Z&to=2023-02-02T00:00:00Z" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/pollen/history/aggregate",{
  params: { 
    code: 69006,
    location_type: 'postal_code',
    iso2_code: 'FR',
    page: 1,
    from: '2023-01-01T00:00:00Z',
    to: '2023-01-02T00:00:00Z'
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "values": [
      {
        "datetime": "2023-02-01T06:00:00.000Z",
        "pollutants": {    
          "grasses": {
              "shortcode": "Gra.",
              "name": "Grasses",
              "unit": "grains/m³",
              "found": true,
              "values": {
                  "mean": 31,
                  "min": 21,
                  "max": 40
              },
              "confidence": 5,
              "indexes": {
                  "mean": {
                      "index_type": "meersens",
                      "index_name": "Meersens",
                      "qualification": "Significant",
                      "icon": null,
                      "color": "#ffb121",
                      "description": "Significant allergy risk",
                      "value": 52.34
                  },
                  "min": {
                      "index_type": "meersens",
                      "index_name": "Meersens",
                      "qualification": "Significant",
                      "icon": null,
                      "color": "#ffb121",
                      "description": "Significant allergy risk",
                      "value": 50.21
                  },
                  "max": {
                      "index_type": "meersens",
                      "index_name": "Meersens",
                      "qualification": "Significant",
                      "icon": null,
                      "color": "#ffb121",
                      "description": "Significant allergy risk",
                      "value": 54.25
                  }
                }
            },
          "olive_tree": {...},
          "alder_tree": {...},
          "mugwort": {...}
        },
        "indexes": {
          "mean": {
              "index_type": "meersens",
              "index_name": "Meersens",
              "qualification": "Significant",
              "icon": null,
              "color": "#ffb121",
              "description": "Significant allergy risk",
              "value": 52.34,
              "main_pollutants": [
                  "grasses"
              ]
          },
          "min": {
              "index_type": "meersens",
              "index_name": "Meersens",
              "qualification": "Significant",
              "icon": null,
              "color": "#ffb121",
              "description": "Significant allergy risk",
              "value": 50.21,
              "main_pollutants": [
                  "grasses"
              ]
          },
          "max": {
              "index_type": "meersens",
              "index_name": "Meersens",
              "qualification": "Significant",
              "icon": null,
              "color": "#ffb121",
              "description": "Significant allergy risk",
              "value": 54.25,
              "main_pollutants": [
                  "grasses"
              ]
          }
        }
      }
    ],
    "page": {
      "totalElements": 24,
      "totalPages": 4,
      "pageNumber": 1,
      "size": 6
    }
}

Returns hourly or daily history pollen data for a given area. For each hour included in the requested timeframe, the minimum, maximum and average pollutants concentrations will be retrieved (if found), along with the computed min, max and mean pollen indexes. Hourly aggregation is only available for a period up to six months ago, and for postal codes. Please note that this is only available for french postal codes so far.

Path

GET https://api.meersens.com/environment/public/pollen/history/aggregate

Query Parameters

Parameter Type   Description Required
code number The postal code of the geographical area to aggregate. true
location_type string The type of the location to apply the aggregation on. true
iso2_code string The ISO 3166-1 alpha-2 code of the country of the requested postal code. true
from string ISO_8601 UTC datetime (including timezone) that indicates the starting date of the history timeframe data. false
(default:24hours ago)
to string ISO_8601 UTC datetime (including timezone) that indicates the ending date of the history timeframe data. false
(default:beginning of current hour)
page number The number of the page to return among the pages of results. false (default: 0)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found.
values array Array of hourly pollen min, max and mean values.
values.datetime string ISO_8601 UTC datetime indicating the time the data refers to for this hourly entry.
values.indexes  object Dictionary of the min, max and mean pollen index objects.
values.indexes.[statistic].index_type  string Unique identifier of the returned pollen index.
values.indexes.[statistic].index_name  string Name of the returned pollen index.
values.indexes.[statistic].qualification  string Pollen index textual representation.
values.indexes.[statistic].description  string Pollen index textual assessment.
values.indexes.[statistic].icon  string Pollen level associated icon (if any, otherwise null).
values.indexes.[statistic].color  string Pollen level hexadecimal color code.
values.indexes.[statistic].value  number Pollen level value (for numeric indexes only, otherwise null).
values.indexes.[statistic].main_pollutants  array Array of main pollutants identifiers.
values.pollutants  object Dictionary of available pollutants at the requested point.
values.pollutants.shortcode  string Pollutant textual shortcode.
values.pollutants.name  string Pollutant full name.
values.pollutants.unit  string Unit in which the pollutant value is returned.
values.pollutants.found  boolean Whether the pollutant value has been found.
values.pollutants.values  object Dictionary of the pollutant values statistics in specified unit.
values.pollutants.values.min  number Minimum value of the pollutant in specified unit on the requested area.
values.pollutants.values.max  number Maximum value of the pollutant in specified unit on the requested area.
values.pollutants.values.mean  number Average value of the pollutant in specified unit on the requested area.
values.pollutants.confidence  number Pollutant value confidence.
values.pollutants.indexes  object Dictionary of the pollutant specific index information statistics over the requested area.
values.pollutants.indexes.[statistic].index_type  string Unique identifier of the returned pollen index.
values.pollutants.indexes.[statistic].index_name  string Name of the returned pollen index.
values.pollutants.indexes.[statistic].qualification  string Pollen index textual representation.
values.pollutants.indexes.[statistic].description  string Pollen index textual assessment.
values.pollutants.indexes.[statistic].icon  string Pollutant level associated icon (if any, otherwise null).
values.pollutants.indexes.[statistic].color  string Pollutant level hexadecimal color code.
values.pollutants.indexes.[statistic].value  number Pollutant level index value (for numeric indexes only, otherwise null).
page object Object containing information about the pagination of the response.
page.totalElements number The total amount of pollen values.
page.totalPages number The amount of pages of pollen values.
page.pageNumber number The number of the page currently returned.
page.size number The amount of pollen values returned per page.

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

Pollen forecast geographical aggregation

Returns hourly forecast pollen data at a given location. For each hour included in the requested timeframe, the minimum, maximum and average pollutants concentrations will be retrieved (if found), along with the computed min, max and mean pollen indexes.The maximum timeframe allowed to be requested is 96 hours, meaning 4 days. Please refer to the above page for details about the query input and output. Please note that this is only available for french postal codes so far.

Path

GET https://api.meersens.com/environment/public/pollen/forecast/aggregate

UV

The UV API lets you request UV index data for a specific location. Retrieved information includes UV index, data confidence, comparison with W.H.O applicable standards & norms and generic health recommendations.

UV indexes

In order to let you easily interpretate environmental data, each one is associated to an environmental index. This index is designed to represent a human-readable assessment of a given environmental quality, simplifying the readings of raw pollutants concentrations and emphasizing eventual country specificities given pollutants levels interpretation.

For UV, Meersens currently supports the following indexes:

ID Name  Numeric Description Pollutants
meersens Meersens UV Index true Meersens proprietary UV Index uvi

UV current conditions

import requests

requests.get("https://api.meersens.com/environment/public/uv/current", headers={
  'apikey': 'your_api_key'
}, params={
  lat: 1.234,
  lng: 5.678
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/uv/current?lat=1.234&lng=5.678" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/uv/current",{
  params: { 
    lat: 1.234,
    lng: 5.678
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "datetime": "2021-11-08T21:00:00.000Z",
    "index": {
        "index_type": "meersens",
        "index_name": "Meersens",
        "qualification": "Moderate",
        "icon": null,
        "color": "#e8c900",
        "value": 34.13,
        "main_pollutants": [
            "uvi"
        ]
    },
    "pollutants": {
        "uvi": {
            "shortcode": "UV",
            "name": "UV Index",
            "unit": "UVI",
            "found": true,
            "value": 4,
            "confidence": 4.5,
            "index": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "Moderate",
                "icon": null,
                "color": "#e8c900",
                "description": "Moderate risk of harm from unprotected sun exposure",
                "value": 14.28
            }
        }
    },
    "health_recommendations": {
        "all": "Degraded UV can cause irritation of the respiratory tract and cause respiratory discomfort.",
        "family": "Children with an immature respiratory system are more impacted by poor UV. Outdoor activities can be maintained as long as there is no respiratory or cardiac discomfort.",
        "sport": "Physical activities cause an increase in respiratory rate which leads to increased exposure to pollutants and potentially to symptoms resulting from them.",
        "pregnancy": "Exposure to pollutants can affect the fetus and pregnancy (lower birth weight, preterm delivery ...)",
        "respiratory": "Air pollution can worsen respiratory pathologies such as asthma, COPD, chronic bronchitis ...",
        "elderly": "With age, the respiratory system can become weakened and pollution can exacerbate respiratory problems",
        "cardiovascular": "Air pollution has been implicated in the development or aggravation of cardiovascular disease"
    }
}

Returns current information about UV conditions for a specific location.

Path

GET https://api.meersens.com/environment/public/uv/current

Query Parameters

Parameter Type   Description Required
lat number Latitude of the location to compute UV conditions at. In WGS84 format. true
lng number Longitude of the location to compute UV conditions at. In WGS84 format. true
index_type string Unique identifier of the desired output UV index. Use reserved keyword local to get the locally applicable index at the point you're requesting data. false
(default:meersens)
health_recommendations boolean Indicates whether health recommendations should be retrieved for this UV levels or not. false
(default:false)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found.
datetime string ISO_8601 UTC datetime indicating the time the data refers to.
index  object UV index object.
index.index_type  string Unique identifier of the returned UV index.
index.index_name  string Name of the returned UV index.
index.qualification  string UV index textual representation.
index.description  string UV index textual assessment.
index.icon  string UV level associated icon (if any, otherwise null).
index.color  string UV level hexadecimal color code.
index.value  number UV level value (for numeric indexes only, otherwise null).
index.main_pollutants  array Array of main pollutants identifiers.
pollutants  object Dictionary of available pollutants at the requested point.
pollutants.shortcode  string Pollutant textual shortcode.
pollutants.name  string Pollutant full name.
pollutants.unit  string Unit in which the pollutant value is returned.
pollutants.found  boolean Whether the pollutant value has been found.
pollutants.value  number Value of the pollutant in specified unit.
pollutants.confidence  number Pollutant value confidence.
pollutants.index  object Pollutant specific index information
pollutants.index.index_type  string Unique identifier of the returned UV index.
pollutants.index.index_name  string Name of the returned UV index.
pollutants.index.qualification  string UV index textual representation.
pollutants.index.description  string UV index textual assessment.
pollutants.index.icon  string Pollutant level associated icon (if any, otherwise null).
pollutants.index.color  string Pollutant level hexadecimal color code.
pollutants.index.value  number Pollutant level index value (for numeric indexes only, otherwise null).
health_recommendations object Dictionary of health recommendations for various population categories, including:
-all : general population
-family : populations with childrens
-sport : sports populations
-pregnancy : pregnant populations
-elderly : elderly populations
-respiratory : populations with respiratory diseases
-cardiovascular : populations with cardiovascular diseases

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

UV history

import requests

requests.get("https://api.meersens.com/environment/public/uv/history", headers={
  'apikey': 'your_api_key'
}, params={
  lat: 1.234,
  lng: 5.678,
  from: '2021-01-01T00:00:00Z',
  to: '2021-01-02T00:00:00Z',
  page: 0
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/uv/history?lat=1.234&lng=5.678&from=2021-01-01T00:00:00Z&to=2021-01-02T00:00:00Z&page=0" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/uv/forecast",{
  params: { 
    lat: 1.234,
    lng: 5.678,
    from: '2021-01-01T00:00:00Z',
    to: '2021-01-02T00:00:00Z',
    page: 0
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "values": [
        {
            "datetime": "2021-11-07T22:00:00.000Z",
            "pollutants": {    
                "uvi": {
                  "shortcode": "UV",
                  "name": "UV Index",
                  "unit": "UVI",
                  "found": true,
                  "value": 4,
                  "confidence": 4.5,
                  "index": {
                      "index_type": "meersens",
                      "index_name": "Meersens",
                      "qualification": "Moderate",
                      "icon": null,
                      "color": "#e8c900",
                      "description": "Moderate risk of harm from unprotected sun exposure",
                      "value": 14.28
                  }
              }
            },
            "index": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "Moderate",
                "icon": null,
                "color": "#e8c900",
                "value": 32.62,
                "main_pollutants": [
                    "uvi"
                ]
            },
            "found": true
        },
        {...}
    ],
     "page": {
        "totalElements": 24,
        "totalPages": 4,
        "pageNumber": 0,
        "size": 6
    }
}

Returns hourly history UV data at a given location. For each hour included in the requested timeframe, the pollutants concentrations will be retrieved (if found), along with the computed UV index. Each returned page will contain up to 6 time points entries.

Path

GET https://api.meersens.com/environment/public/uv/history

Query Parameters

Parameter Type   Description Required
lat number Latitude of the location to compute UV conditions at. In WGS84 format. true
lng number Longitude of the location to compute UV conditions at. In WGS84 format. true
from string ISO_8601 UTC datetime (including timezone) that indicates the starting date of the forecast timeframe data. false
(default:24hours ago)
to string ISO_8601 UTC datetime (including timezone) that indicates the ending date of the forecast timeframe data. false
(default:beginning of current hour)
index_type string Unique identifier of the desired output UV index. Use reserved keyword local to get the locally applicable index at the point you're requesting data. false
(default:meersens)
page number The number of the page to return among the pages of results. false (default: 0)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found over the period.
values array Array of hourly UV values.
values.datetime string ISO_8601 UTC datetime indicating the time the data refers to for this hourly entry.
values.index  object UV index object for this hourly entry.
values.index.index_type  string Unique identifier of the returned UV index.
values.index.index_name  string Name of the returned UV index.
values.index.qualification  string UV index textual representation.
values.index.description  string UV index textual assessment.
values.index.icon  string UV level associated icon (if any, otherwise null).
values.index.color  string UV level hexadecimal color code.
values.index.value  number UV level value (for numeric indexes only, otherwise null).
values.index.main_pollutants  array Array of main pollutants identifiers.
values.pollutants  object Dictionary of available pollutants at the requested point for this hourly entry.
values.pollutants.shortcode  string Pollutant textual shortcode.
values.pollutants.name  string Pollutant full name.
values.pollutants.unit  string Unit in which the pollutant value is returned.
values.pollutants.found  boolean Whether the pollutant value has been found.
values.pollutants.value  number Value of the pollutant in specified unit.
values.pollutants.confidence  number Pollutant value confidence.
values.pollutants.index  object Pollutant specific index information
values.pollutants.index.index_type  string Unique identifier of the returned UV index.
values.pollutants.index.index_name  string Name of the returned UV index.
values.pollutants.index.qualification  string UV index textual representation.
values.pollutants.index.description  string UV index textual assessment.
values.pollutants.index.icon  string Pollutant level associated icon (if any, otherwise null).
values.pollutants.index.color  string Pollutant level hexadecimal color code.
values.pollutants.index.value  number Pollutant level index value (for numeric indexes only, otherwise null).
page object Object containing information about the pagination of the response.
page.totalElements number The total amount of UV values.
page.totalPages number The amount of pages of UV values.
page.pageNumber number The number of the page currently returned.
page.size number The amount of UV values returned per page.

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

UV forecast

import requests

requests.get("https://api.meersens.com/environment/public/uv/forecast", headers={
  'apikey': 'your_api_key'
}, params={
  lat: 1.234,
  lng: 5.678,
  from: '2021-01-01T00:00:00Z',
  to: '2021-01-02T00:00:00Z',
  page: 0
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/uv/forecast?lat=1.234&lng=5.678&from=2021-01-01T00:00:00Z&to=2021-01-02T00:00:00Z&page=0" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/uv/forecast",{
  params: { 
    lat: 1.234,
    lng: 5.678,
    from: '2021-01-01T00:00:00Z',
    to: '2021-01-02T00:00:00Z',
    page: 0
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "values": [
        {
            "datetime": "2021-11-07T22:00:00.000Z",
            "pollutants": {    
                "uvi": {
                  "shortcode": "UV",
                  "name": "UV Index",
                  "unit": "UVI",
                  "found": true,
                  "value": 4,
                  "confidence": 4.5,
                  "index": {
                      "index_type": "meersens",
                      "index_name": "Meersens",
                      "qualification": "Moderate",
                      "icon": null,
                      "color": "#e8c900",
                      "description": "Moderate risk of harm from unprotected sun exposure",
                      "value": 14.28
                  }
              }
            },
            "index": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "Moderate",
                "icon": null,
                "color": "#e8c900",
                "value": 32.62,
                "main_pollutants": [
                    "uvi"
                ]
            },
            "found": true
        },
        {...}
    ],
    "page": {
        "totalElements": 24,
        "totalPages": 4,
        "pageNumber": 0,
        "size": 6
    }
}

Returns paginated hourly forecast UV data at a given location. For each hour included in the requested timeframe, the pollutants concentrations will be retrieved (if found), along with the computed UV index. The maximum timeframe allowed to be requested is 120 hours, meaning 5 days. Each returned page will contain up to 6 time points entries.

Path

GET https://api.meersens.com/environment/public/uv/forecast

Query Parameters

Parameter Type   Description Required
lat number Latitude of the location to compute UV conditions at. In WGS84 format. true
lng number Longitude of the location to compute UV conditions at. In WGS84 format. true
from string ISO_8601 UTC datetime (including timezone) that indicates the starting date of the forecast timeframe data. false
(default:24hours ago)
to string ISO_8601 UTC datetime (including timezone) that indicates the ending date of the forecast timeframe data. false
(default:beginning of current hour)
index_type string Unique identifier of the desired output UV index. Use reserved keyword local to get the locally applicable index at the point you're requesting data. false
(default:meersens)
page number The number of the page to return among the pages of paginated results. false (default: 0)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found over the period.
values array Array of hourly UV values.
values.datetime string ISO_8601 UTC datetime indicating the time the data refers to for this hourly entry.
values.index  object UV index object for this hourly entry.
values.index.index_type  string Unique identifier of the returned UV index.
values.index.index_name  string Name of the returned UV index.
values.index.qualification  string UV index textual representation.
values.index.description  string UV index textual assessment.
values.index.icon  string UV level associated icon (if any, otherwise null).
values.index.color  string UV level hexadecimal color code.
values.index.value  number UV level value (for numeric indexes only, otherwise null).
values.index.main_pollutants  array Array of main pollutants identifiers.
values.pollutants  object Dictionary of available pollutants at the requested point for this hourly entry.
values.pollutants.shortcode  string Pollutant textual shortcode.
values.pollutants.name  string Pollutant full name.
values.pollutants.unit  string Unit in which the pollutant value is returned.
values.pollutants.found  boolean Whether the pollutant value has been found.
values.pollutants.value  number Value of the pollutant in specified unit.
values.pollutants.confidence  number Pollutant value confidence.
values.pollutants.index  object Pollutant specific index information
values.pollutants.index.index_type  string Unique identifier of the returned UV index.
values.pollutants.index.index_name  string Name of the returned UV index.
values.pollutants.index.qualification  string UV index textual representation.
values.pollutants.index.description  string UV index textual assessment.
values.pollutants.index.icon  string Pollutant level associated icon (if any, otherwise null).
values.pollutants.index.color  string Pollutant level hexadecimal color code.
values.pollutants.index.value  number Pollutant level index value (for numeric indexes only, otherwise null).
page object Object containing information about the pagination of the response.
page.totalElements number The total amount of UV values.
page.totalPages number The amount of pages of UV values.
page.pageNumber number The number of the page currently returned.
page.size number The amount of UV values returned per page.

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

UV geographical aggregation

import requests

requests.get("https://api.meersens.com/environment/public/uv/current/aggregate", headers={
  'apikey': 'your_api_key'
}, params={
  code: 69006,
  location_type: 'postal_code',
  iso2_code: 'FR'
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/uv/current/aggregate?code=69006&iso2_code=fr&location_type=postal_code" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/uv/current/aggregate",{
  params: { 
    code: 69006,
    location_type: 'postal_code',
    iso2_code: 'FR'
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "datetime": "2023-04-07T15:00:00.000Z",
    "indexes": {
        "mean": {
            "index_type": "meersens",
            "index_name": "Meersens",
            "qualification": "Low",
            "icon": null,
            "color": "#05b3a4",
            "description": "No protection needed",
            "value": 8.5,
            "main_pollutants": [
                "uvi"
            ]
        },
        "min": {
            "index_type": "meersens",
            "index_name": "Meersens",
            "qualification": "Low",
            "icon": null,
            "color": "#05b3a4",
            "description": "No protection needed",
            "value": 8.5,
            "main_pollutants": [
                "uvi"
            ]
        },
        "max": {
            "index_type": "meersens",
            "index_name": "Meersens",
            "qualification": "Low",
            "icon": null,
            "color": "#05b3a4",
            "description": "No protection needed",
            "value": 8.5,
            "main_pollutants": [
                "uvi"
            ]
        }
    },
    "pollutants": {
        "uvi": {
            "shortcode": "UVI",
            "name": "UV index",
            "unit": "UVI",
            "found": true,
            "values": {
                "mean": 1,
                "min": 1,
                "max": 1
            },
            "confidence": 5,
            "indexes": {
                "mean": {
                    "index_type": "meersens",
                    "index_name": "Meersens",
                    "qualification": "Low",
                    "icon": null,
                    "color": "#05b3a4",
                    "description": "No protection needed",
                    "value": 8.5
                },
                "min": {
                    "index_type": "meersens",
                    "index_name": "Meersens",
                    "qualification": "Low",
                    "icon": null,
                    "color": "#05b3a4",
                    "description": "No protection needed",
                    "value": 8.5
                },
                "max": {
                    "index_type": "meersens",
                    "index_name": "Meersens",
                    "qualification": "Low",
                    "icon": null,
                    "color": "#05b3a4",
                    "description": "No protection needed",
                    "value": 8.5
                }
            }
        }
    }
}

Returns current information about uv conditions for a given postal code. The returned results give an overview of the minimum, maximum and average values on the area covered by the specified postal code. Please note that this is only available for french postal codes so far.

Path

GET https://api.meersens.com/environment/public/uv/current/aggregate

Query Parameters

Parameter Type   Description Required
code number The postal code of the geographical area to aggregate. true
location_type string The type of the location to apply the aggregation on ("postal_code"). true
iso2_code string The ISO 3166-1 alpha-2 code of the country of the requested postal code. true
health_recommendations boolean Indicates whether health recommendations should be retrieved for this UVs levels or not. false
(default:false)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found.
datetime string ISO_8601 UTC datetime indicating the time the data refers to.
indexes  object Dictionary of the min, max and mean UV index objects.
indexes.[statistic].index_type  string Unique identifier of the returned UV index.
indexes.[statistic].index_name  string Name of the returned UV index.
indexes.[statistic].qualification  string UV index textual representation.
indexes.[statistic].description  string UV index textual assessment.
indexes.[statistic].icon  string UV level associated icon (if any, otherwise null).
indexes.[statistic].color  string UV level hexadecimal color code.
indexes.[statistic].value  number UV level value (for numeric indexes only, otherwise null).
indexes.[statistic].main_pollutants  array Array of main pollutants identifiers.
pollutants  object Dictionary of available pollutants at the requested point.
pollutants.shortcode  string Pollutant textual shortcode.
pollutants.name  string Pollutant full name.
pollutants.unit  string Unit in which the pollutant value is returned.
pollutants.found  boolean Whether the pollutant value has been found.
pollutants.values  object Dictionary of the pollutant values statistics in specified unit.
pollutants.values.min  number Minimum value of the pollutant in specified unit on the requested area.
pollutants.values.max  number Maximum value of the pollutant in specified unit on the requested area.
pollutants.values.mean  number Average value of the pollutant in specified unit on the requested area.
pollutants.confidence  number Pollutant value confidence.
pollutants.indexes  object Dictionary of the pollutant specific index information statistics over the requested area.
pollutants.indexes.[statistic].index_type  string Unique identifier of the returned UV index.
pollutants.indexes.[statistic].index_name  string Name of the returned UV index.
pollutants.indexes.[statistic].qualification  string UV index textual representation.
pollutants.indexes.[statistic].description  string UV index textual assessment.
pollutants.indexes.[statistic].icon  string Pollutant level associated icon (if any, otherwise null).
pollutants.indexes.[statistic].color  string Pollutant level hexadecimal color code.
pollutants.indexes.[statistic].value  number Pollutant level index value (for numeric indexes only, otherwise null).
health_recommendations object Dictionary of health recommendations for various population categories, including:
-all : general population
-family : populations with childrens
-sport : sports populations
-pregnancy : pregnant populations
-elderly : elderly populations
-respiratory : populations with respiratory diseases
-cardiovascular : populations with cardiovascular diseases
The health recommendations are computed using the mean values of the current conditions over the specified area.

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

UV history geographical aggregation

import requests

requests.get("https://api.meersens.com/environment/public/uv/history/aggregate", headers={
  'apikey': 'your_api_key'
}, params={
  code: 69006,
  location_type: 'postal_code',
  iso2_code: 'FR',
  page: 1,
  from: '2023-01-01T00:00:00Z',
  to: '2023-01-02T00:00:00Z'
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/uv/history/aggregate?location_type=postal_code&iso2_code=fr&duration=hour&code=69006&page=1&from=2023-02-01T00:00:00Z&to=2023-02-02T00:00:00Z" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/uv/history",{
  params: { 
    code: 69006,
    location_type: 'postal_code',
    iso2_code: 'FR',
    duration: 'hour',
    page: 1,
    from: '2023-02-01T00:00:00Z',
    to: '2023-02-02T00:00:00Z'
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
  "found": true,
  "values": [
    {
      "datetime": "2022-06-01T06:00:00.000Z",
      "found": true,
      "pollutants": {
          "uvi": {
              "shortcode": "UVI",
              "name": "UV index",
              "unit": "UVI",
              "found": true,
              "values": {
                  "mean": 1,
                  "min": 1,
                  "max": 1
              },
              "confidence": 5,
              "indexes": {
                  "mean": {
                      "index_type": "meersens",
                      "index_name": "Meersens",
                      "qualification": "Low",
                      "icon": null,
                      "color": "#05b3a4",
                      "description": "No protection needed",
                      "value": 8.5
                  },
                  "min": {
                      "index_type": "meersens",
                      "index_name": "Meersens",
                      "qualification": "Low",
                      "icon": null,
                      "color": "#05b3a4",
                      "description": "No protection needed",
                      "value": 8.5
                  },
                  "max": {
                      "index_type": "meersens",
                      "index_name": "Meersens",
                      "qualification": "Low",
                      "icon": null,
                      "color": "#05b3a4",
                      "description": "No protection needed",
                      "value": 8.5
                  }
              }
          }
        },
        "indexes": {
            "mean": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "Low",
                "icon": null,
                "color": "#05b3a4",
                "description": "No protection needed",
                "value": 8.5,
                "main_pollutants": [
                    "uvi"
                ]
            },
            "min": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "Low",
                "icon": null,
                "color": "#05b3a4",
                "description": "No protection needed",
                "value": 8.5,
                "main_pollutants": [
                    "uvi"
                ]
            },
            "max": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "Low",
                "icon": null,
                "color": "#05b3a4",
                "description": "No protection needed",
                "value": 8.5,
                "main_pollutants": [
                    "uvi"
                ]
            }
        }
    },
  ],
  "page": {
    "totalElements": 24,
    "totalPages": 4,
    "pageNumber": 1,
    "size": 6
  }
}

Returns hourly or daily history UV data for a given area or location. For each time point included in the requested timeframe, the minimum, maximum and average pollutants concentrations will be retrieved (if found), along with the computed min, max and mean UV indexes. Hourly aggregation is only available for a period up to six months ago, and for postal codes. For daily aggregation, it is possible to restrict the data to a specific period of the day: morning, midday or afternoon. Please note that this is only available for french postal codes so far.

Path

GET https://api.meersens.com/environment/public/UV/history/aggregate

Query Parameters

Parameter Type   Description Required
location_type string The type of the location to apply the aggregation on ("point" or "postal_code"). true
code number The postal code of the geographical area to aggregate. Required if location_type = "postal_code" false
iso2_code string The ISO 3166-1 alpha-2 code of the country of the requested postal code. Required if location_type = "postal_code" false
lat number The latitude of the point to request daily values for. Required if location_type = "point" false
lng number The longitude of the point to request daily values for. Required if location_type = "point" false
duration string The duration of the temporal aggregation ("day", "morning", "midday", "afternoon", or "hour") false (default: "hour")
from string ISO_8601 UTC datetime (including timezone) that indicates the starting date of the history timeframe data. false
(default:24hours ago)
to string ISO_8601 UTC datetime (including timezone) that indicates the ending date of the history timeframe data. false
(default:beginning of current hour)
page number The number of the page to return among the pages of results. false (default: 0)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found.
values array Array of hourly, period or daily UV min, max and mean values.
values.datetime string ISO_8601 UTC datetime indicating the time the data refers to for this hourly or daily entry. If a specific period (morning, afternoon or midday) was requested, the datetime represents the day of that period.
values.indexes  object Dictionary of the min, max and mean UV index objects.
values.indexes.[statistic].index_type  string Unique identifier of the returned UV index.
values.indexes.[statistic].index_name  string Name of the returned UV index.
values.indexes.[statistic].qualification  string UV index textual representation.
values.indexes.[statistic].description  string UV index textual assessment.
values.indexes.[statistic].icon  string UV level associated icon (if any, otherwise null).
values.indexes.[statistic].color  string UV level hexadecimal color code.
values.indexes.[statistic].value  number UV level value (for numeric indexes only, otherwise null).
values.indexes.[statistic].main_pollutants  array Array of main pollutants identifiers.
values.pollutants  object Dictionary of available pollutants at the requested point.
values.pollutants.shortcode  string Pollutant textual shortcode.
values.pollutants.name  string Pollutant full name.
values.pollutants.unit  string Unit in which the pollutant value is returned.
values.pollutants.found  boolean Whether the pollutant value has been found.
values.pollutants.values  object Dictionary of the pollutant values statistics in specified unit.
values.pollutants.values.min  number Minimum value of the pollutant in specified unit on the requested area.
values.pollutants.values.max  number Maximum value of the pollutant in specified unit on the requested area.
values.pollutants.values.mean  number Average value of the pollutant in specified unit on the requested area.
values.pollutants.confidence  number Pollutant value confidence.
values.pollutants.indexes  object Dictionary of the pollutant specific index information statistics over the requested area.
values.pollutants.indexes.[statistic].index_type  string Unique identifier of the returned UV index.
values.pollutants.indexes.[statistic].index_name  string Name of the returned UV index.
values.pollutants.indexes.[statistic].qualification  string UV index textual representation.
values.pollutants.indexes.[statistic].description  string UV index textual assessment.
values.pollutants.indexes.[statistic].icon  string Pollutant level associated icon (if any, otherwise null).
values.pollutants.indexes.[statistic].color  string Pollutant level hexadecimal color code.
values.pollutants.indexes.[statistic].value  number Pollutant level index value (for numeric indexes only, otherwise null).
page object Object containing information about the pagination of the response.
page.totalElements number The total amount of UV values.
page.totalPages number The amount of pages of UV values.
page.pageNumber number The number of the page currently returned.
page.size number The amount of UV values returned per page.

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

UV forecast geographical aggregation

Returns hourly forecast UV data at a given location. For each hour included in the requested timeframe, the minimum, maximum and average pollutants concentrations will be retrieved (if found), along with the computed min, max and mean UV indexes. The maximum timeframe allowed to be requested is 120 hours, meaning 5 days. Please refer to the above page for details about the query input and output. Daily aggregation is not supported for forecast data. Please note that this is only available for french postal codes so far.

Path

GET https://api.meersens.com/environment/public/UV/forecast/aggregate

Water quality

The water quality API lets you request tap water quality data for a specific location. Retrieved information includes pollutants concentration levels, data confidence, comparison with W.H.O applicable standards & norms and generic health recommendations.
Please note that tap water quality data are computed at the city/distribution network level, meaning that points served by the same tap water network will have same pollutants data.

Water quality indexes

In order to let you easily interpretate environmental data, each one is associated to an environmental index. This index is designed to represent a human-readable assessment of a given environmental quality, simplifying the readings of raw pollutants concentrations and emphasizing eventual country specificities given pollutants levels interpretation.

For Air Quality, Meersens currently supports the following indexes:

ID Name  Numeric Description Pollutants
meersens Meersens Water quality Index true Meersens proprietary Water quality Index acrylamide, ammonium, arsenic, bap, barium, benzene, boron, bromates, cadmium, chlorate, chlorides, chlorine, chlorites, cobalt, copper, epichlorohydrin, iron, lead, manganese, mercury, microcystin-lr, nickel, nitrates, nitrites, pahs, pcb, pesticides, radon, selenium, strontium, sulphates, tetrachloroethylene and trichloroethylene, thms, total aluminium, total chromium, tritium, uranium
meersens_mbi Meersens Water Microbiological Index true Meersens proprietary Water Microbiological Index coli, coliform, enterococci, turbidity
meersens_mi Meersens Water Minerals Index true Meersens proprietary Water Minerals Index calcium, fluorides, magnesium, sodium
meersens_pi Meersens Water Physical Index true Meersens proprietary Water Physical Index conductivity, hardness, ph, temperature

Water quality current conditions

import requests

requests.get("https://api.meersens.com/environment/public/water/current", headers={
  'apikey': 'your_api_key'
}, params={
  lat: 1.234,
  lng: 5.678
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/water/current?lat=1.234&lng=5.678" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/water/current",{
  params: { 
    lat: 1.234,
    lng: 5.678
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "datetime": "2021-11-08T21:00:00.000Z",
    "index": {
        "index_type": "meersens",
        "index_name": "Meersens",
        "qualification": "Neutral",
        "icon": null,
        "color": "#05b3a4",
        "value": 5,
        "main_pollutants": [
            "pH"
        ]
    },
    "pollutants": {
        "pH": {
            "shortcode": "pH",
            "name": "pH",
            "unit": "",
            "found": true,
            "value": 7.4,
            "confidence": 4.5,
            "index": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "Neutral",
                "icon": null,
                "color": "#05b3a4",
                "description": "Water pH varies most often between 6.5 and 8.5, water can therefore be weakly acidic or basic that does not pose a problem for health.",
                "value": 5
            }
        },
        ...
    },
    "health_recommendations": {
        "all": "Degraded water quality can cause irritation of the respiratory tract and cause respiratory discomfort.",
        "family": "Children with an immature respiratory system are more impacted by poor water quality. Outdoor activities can be maintained as long as there is no respiratory or cardiac discomfort.",
        "sport": "Physical activities cause an increase in respiratory rate which leads to increased exposure to pollutants and potentially to symptoms resulting from them.",
        "pregnancy": "Exposure to pollutants can affect the fetus and pregnancy (lower birth weight, preterm delivery ...)",
        "respiratory": "Air pollution can worsen respiratory pathologies such as asthma, COPD, chronic bronchitis ...",
        "elderly": "With age, the respiratory system can become weakened and pollution can exacerbate respiratory problems",
        "cardiovascular": "Air pollution has been implicated in the development or aggravation of cardiovascular disease"
    }
}

Returns current information about water quality conditions for a specific location.

Path

GET https://api.meersens.com/environment/public/water/current

Query Parameters

Parameter Type   Description Required
lat number Latitude of the location to compute water quality conditions at. In WGS84 format. true
lng number Longitude of the location to compute water quality conditions at. In WGS84 format. true
index_type string Unique identifier of the desired output water quality index. Use reserved keyword local to get the locally applicable index at the point you're requesting data. false
(default:meersens)
health_recommendations boolean Indicates whether health recommendations should be retrieved for this water quality levels or not. false
(default:false)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found.
datetime string ISO_8601 UTC datetime indicating the time the data refers to.
index  object Water quality index object.
index.index_type  string Unique identifier of the returned water quality index.
index.index_name  string Name of the returned water quality index.
index.qualification  string Water quality index textual representation.
index.description  string Water quality index textual assessment.
index.icon  string Water quality level associated icon (if any, otherwise null).
index.color  string Water quality level hexadecimal color code.
index.value  number Water quality level value (for numeric indexes only, otherwise null).
index.main_pollutants  array Array of main pollutants identifiers.
pollutants  object Dictionary of available pollutants at the requested point.
pollutants.shortcode  string Pollutant textual shortcode.
pollutants.name  string Pollutant full name.
pollutants.unit  string Unit in which the pollutant value is returned.
pollutants.found  boolean Whether the pollutant value has been found.
pollutants.value  number Value of the pollutant in specified unit.
pollutants.confidence  number Pollutant value confidence.
pollutants.index  object Pollutant specific index information
pollutants.index.index_type  string Unique identifier of the returned water quality index.
pollutants.index.index_name  string Name of the returned water quality index.
pollutants.index.qualification  string Water quality index textual representation.
pollutants.index.description  string Water quality index textual assessment.
pollutants.index.icon  string Pollutant level associated icon (if any, otherwise null).
pollutants.index.color  string Pollutant level hexadecimal color code.
pollutants.index.value  number Pollutant level index value (for numeric indexes only, otherwise null).
health_recommendations object Dictionary of health recommendations for various population categories, including:
-all : general population
-family : populations with childrens
-sport : sports populations
-pregnancy : pregnant populations
-elderly : elderly populations
-respiratory : populations with respiratory diseases
-cardiovascular : populations with cardiovascular diseases

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

Water quality history

import requests

requests.get("https://api.meersens.com/environment/public/water/history", headers={
  'apikey': 'your_api_key'
}, params={
  lat: 1.234,
  lng: 5.678,
  from: '2021-01-01T00:00:00Z',
  to: '2021-01-02T00:00:00Z',
  page: 0
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/water/history?lat=1.234&lng=5.678&from=2021-01-01T00:00:00Z&to=2021-01-02T00:00:00Z&page=0" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/water/history",{
  params: { 
    lat: 1.234,
    lng: 5.678,
    from: '2021-01-01T00:00:00Z',
    to: '2021-01-02T00:00:00Z',
    page: 0
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "values": [
        {
            "datetime": "2021-11-07T22:00:00.000Z",
            "pollutants": {    
                "pH": {
                  "shortcode": "pH",
                  "name": "pH",
                  "unit": "",
                  "found": true,
                  "value": 7.4,
                  "confidence": 4.5,
                  "index": {
                      "index_type": "meersens",
                      "index_name": "Meersens",
                      "qualification": "Neutral",
                      "icon": null,
                      "color": "#05b3a4",
                      "description": "Water pH varies most often between 6.5 and 8.5, water can therefore be weakly acidic or basic that does not pose a problem for health.",
                      "value": 5
                  }
              },
              ...
            },
            "index": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "Neutral",
                "icon": null,
                "color": "#05b3a4",
                "value": 5,
                "main_pollutants": [
                    "pH"
                ]
            },
            "found": true
        },
        {...}
    ],
    "page": {
      "totalElements": 24,
      "totalPages": 4,
      "pageNumber": 0,
      "size": 6
  }
}

Returns paginated hourly history water quality data at a given location. For each hour included in the requested timeframe, the pollutants concentrations will be retrieved (if found), along with the computed water quality index. Each returned page will contain up to 6 time points entries.

Path

GET https://api.meersens.com/environment/public/water/history

Query Parameters

Parameter Type   Description Required
lat number Latitude of the location to compute water quality conditions at. In WGS84 format. true
lng number Longitude of the location to compute water quality conditions at. In WGS84 format. true
from string ISO_8601 UTC datetime (including timezone) that indicates the starting date of the history timeframe data. false
(default:24hours ago)
to string ISO_8601 UTC datetime (including timezone) that indicates the ending date of the history timeframe data. false
(default:beginning of current hour)
index_type string Unique identifier of the desired output water quality index. Use reserved keyword local to get the locally applicable index at the point you're requesting data. false
(default:meersens)
page number The number of the page to return among the pages of results. false (default: 0)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found over the period.
values array Array of hourly water quality values.
values.datetime string ISO_8601 UTC datetime indicating the time the data refers to for this hourly entry.
values.index  object Water quality index object for this hourly entry.
values.index.index_type  string Unique identifier of the returned water quality index.
values.index.index_name  string Name of the returned water quality index.
values.index.qualification  string Water quality index textual representation.
values.index.description  string Water quality index textual assessment.
values.index.icon  string Water quality level associated icon (if any, otherwise null).
values.index.color  string Water quality level hexadecimal color code.
values.index.value  number Water quality level value (for numeric indexes only, otherwise null).
values.index.main_pollutants  array Array of main pollutants identifiers.
values.pollutants  object Dictionary of available pollutants at the requested point for this hourly entry.
values.pollutants.shortcode  string Pollutant textual shortcode.
values.pollutants.name  string Pollutant full name.
values.pollutants.unit  string Unit in which the pollutant value is returned.
values.pollutants.found  boolean Whether the pollutant value has been found.
values.pollutants.value  number Value of the pollutant in specified unit.
values.pollutants.confidence  number Pollutant value confidence.
values.pollutants.index  object Pollutant specific index information
values.pollutants.index.index_type  string Unique identifier of the returned water quality index.
values.pollutants.index.index_name  string Name of the returned water quality index.
values.pollutants.index.qualification  string Water quality index textual representation.
values.pollutants.index.description  string Water quality index textual assessment.
values.pollutants.index.icon  string Pollutant level associated icon (if any, otherwise null).
values.pollutants.index.color  string Pollutant level hexadecimal color code.
values.pollutants.index.value  number Pollutant level index value (for numeric indexes only, otherwise null).
page object Object containing information about the pagination of the response.
page.totalElements number The total amount of water quality values.
page.totalPages number The amount of pages of water quality values.
page.pageNumber number The number of the page currently returned.
page.size number The amount of water quality values returned per page.

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

Weather

The weather API lets you request weather parameters data for a specific location. Main weather parameters are available, including:

Weather quality index

In order to let you easily interpretate environmental data, each one is associated to an environmental index. This index is designed to represent a human-readable assessment of a given environmental quality, simplifying the readings of raw parameters concentrations and emphasizing eventual country specificities given pollutants levels interpretation.

For Weather, Meersens currently supports the following index:

ID Name  Numeric Description Pollutants
meersens Meersens Weather Index true Meersens proprietary Weather Index apparent_temperature, temperature, humidity, precipitations, pressure, wind_speed

Weather current conditions

import requests

requests.get("https://api.meersens.com/environment/public/weather/current", headers={
  'apikey': 'your_api_key'
}, params={
  lat: 1.234,
  lng: 5.678
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/weather/current?lat=1.234&lng=5.678" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/weather/current",{
  params: { 
    lat: 1.234,
    lng: 5.678
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "datetime": "2023-09-05T16:00:00.000Z",
    "index": {
        "index_type": "meersens",
        "index_name": "Meersens",
        "qualification": "Mediocre",
        "icon": null,
        "color": "#ffb121",
        "description": "Mediocre weather",
        "value": 56.6,
        "main_pollutants": [
            "apparent_temperature"
        ]
    },
    "parameters": {
        "apparent_temperature": {
            "shortcode": "aT",
            "name": "Apparent temperature",
            "found": true,
            "value": 35.3,
            "unit": "°C",
            "confidence": 5,
            "index": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "Mediocre",
                "icon": null,
                "color": "#ffb121",
                "description": "Heat stroke, heat cramps or heat exhaustion possible ",
                "value": 56.6
            }
        },
        "ww": {
            "shortcode": "WW",
            "name": "Significant weather",
            "found": true,
            "qualification": "Clear sky",
            "description": "Cloud development not observed or observable",
            "icon": "https://s3.eu-west-2.amazonaws.com/weather.meersens/icons/sunny.png",
            "confidence": 5,
            "index": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": null,
                "color": "#9A9A9A",
                "description": null,
                "value": null
            }
        },
        "temperature": {...},
        "humidity": {...},
        "pressure": {...},
        "wind_speed": {...},
        "wind_direction": {...},
        "cloud_cover": {...},
        "precipitations": {...}
    }
}

Returns current information about weather conditions for a specific location.

Path

GET https://api.meersens.com/environment/public/weather/current

Query Parameters

Parameter Type   Description Required
lat number Latitude of the location to compute weather conditions at. In WGS84 format. true
lng number Longitude of the location to compute weather conditions at. In WGS84 format. true
system string System to be used for parameters units, can be either metric (default) or imperial false
(default: metric)

Response attributes

Parameter Type Description
found  boolean Whether at least one parameter value has been found.
datetime string ISO_8601 UTC datetime indicating the time the data refers to.
index  object Weather index object.
index.index_type  string Unique identifier of the returned weather index.
index.index_name  string Name of the returned weather index.
index.qualification  string Weather index textual representation.
index.description  string Weather index textual assessment.
index.icon  string Weather level associated icon (if any, otherwise null).
index.color  string Weather level hexadecimal color code.
index.value  number Weather level value (for numeric indexes only, otherwise null).
index.main_pollutants  array Array of main parameters identifiers.
parameters  object Dictionary of available parameters at the requested point.
parameters.shortcode  string Parameter textual shortcode.
parameters.name  string Parameter full name.
parameters.unit  string Unit in which the parameter value is returned (except for parameter ww).
parameters.found  boolean Whether the parameter value has been found.
parameters.confidence  number Parameter value confidence.
parameters.value  number Value of the parameter in specified unit (except for parameter ww).
parameters.qualification  string Textual representation of the significant weather (only for parameter ww).
parameters.description  string Detailed description of the significant weather (only for parameter ww).
parameters.icon  string Icon (format png) matching this significant weather (only for parameter ww).
parameters.index  object Parameter specific index information
parameters.index.index_type  string Unique identifier of the returned weather index.
parameters.index.index_name  string Name of the returned weather index.
parameters.index.qualification  string Weather index textual representation.
parameters.index.description  string Weather index textual assessment.
parameters.index.icon  string Parameter level associated icon (if any, otherwise null).
parameters.index.color  string Parameter level hexadecimal color code.
parameters.index.value  number Parameter level index value (for numeric indexes only, otherwise null).

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

Weather history

import requests

requests.get("https://api.meersens.com/environment/public/weather/history", headers={
  'apikey': 'your_api_key'
}, params={
  lat: 1.234,
  lng: 5.678,
  from: '2021-01-01T00:00:00Z',
  to: '2021-01-02T00:00:00Z',
  page: 0
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/weather/history?lat=1.234&lng=5.678&from=2021-01-01T00:00:00Z&to=2021-01-02T00:00:00Z&page=0" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/weather/forecast",{
  params: { 
    lat: 1.234,
    lng: 5.678,
    from: '2021-01-01T00:00:00Z',
    to: '2021-01-02T00:00:00Z',
    page: 0
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "values": [
        {
            "found": true,
            "datetime": "2023-09-05T07:00:00.000Z",
            "index": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "Good",
                "icon": null,
                "color": "#6cd2c9",
                "description": "Good atmosphere",
                "value": 14.6,
                "main_pollutants": [
                    "temperature"
                ]
            },
            "parameters": {
                "temperature": {
                    "shortcode": "T",
                    "name": "Temperature",
                    "found": true,
                    "value": 24.4,
                    "unit": "°C",
                    "confidence":5,
                    "index": {
                        "index_type": "meersens",
                        "index_name": "Meersens",
                        "qualification": "Good",
                        "icon": null,
                        "color": "#6cd2c9",
                        "description": "Mild temperature",
                        "value": 14.6
                    }
                },
                "ww": {
                    "shortcode": "WW",
                    "name": "Significant weather",
                    "found": false,
                    "qualification": "Mainly clear",
                    "description": "Clouds dissolving or becoming less developed",
                    "icon": "https://s3.eu-west-2.amazonaws.com/weather.meersens/icons/mainly_clear.png",
                    "confidence": 5,
                    "index": {
                        "index_type": "meersens",
                        "index_name": "Meersens",
                        "qualification": null,
                        "color": "#9A9A9A",
                        "description": null,
                        "value": null
                    }
                },
                "apparent_temperature": {...},
                "humidity": {...},
                "pressure": {...},
                "wind_speed": {...},
                "wind_direction": {...},
                "cloud_cover": {...},
                "precipitations": {...}
            }
        }
        {...}
    ],
    "page": {
      "totalElements": 24,
      "totalPages": 4,
      "pageNumber": 0,
      "size": 6
    }
}

Returns paginated hourly history weather data at a given location. For each hour included in the requested timeframe, the parameter values will be retrieved (if found). Each returned page will contain up to 6 time points entries.

Path

GET https://api.meersens.com/environment/public/weather/history

Query Parameters

Parameter Type   Description Required
lat number Latitude of the location to compute weather conditions at. In WGS84 format. true
lng number Longitude of the location to compute weather conditions at. In WGS84 format. true
from string ISO_8601 UTC datetime (including timezone) that indicates the starting date of the history timeframe data. false
(default:24hours ago)
to string ISO_8601 UTC datetime (including timezone) that indicates the ending date of the history timeframe data. false
(default:beginning of current hour)
system string System to be used for parameters units, can be either metric (default) or imperial false
(default: metric)
page number The number of the page to return among the pages of results. false (default: 0)

Response attributes

Parameter Type Description
found  boolean Whether at least one parameter value has been found over the period.
values array Array of hourly weather values.
values.datetime string ISO_8601 UTC datetime indicating the time the data refers to for this hourly entry.
values.index  object Weather index object for this hourly entry.
values.index.index_type  string Unique identifier of the returned weather index.
values.index.index_name  string Name of the returned weather index.
values.index.qualification  string Weather index textual representation.
values.index.description  string Weather index textual assessment.
values.index.icon  string Weather level associated icon (if any, otherwise null).
values.index.color  string Weather level hexadecimal color code.
values.index.value  number Weather level value (for numeric indexes only, otherwise null).
values.index.main_pollutants  array Array of main parameters identifiers.
values.parameters  object Dictionary of available parameters at the requested point for this hourly entry.
values.parameters.shortcode  string Parameter textual shortcode.
values.parameters.name  string Parameter full name.
values.parameters.unit  string Unit in which the parameter value is returned (except for parameter ww).
values.parameters.found  boolean Whether the parameter value has been found.
values.parameters.value  number Value of the parameter in specified unit (except for parameter ww).
values.parameters.confidence  number Parameter value confidence.
values.parameters.qualification  string Textual representation of the significant weather (only for parameter ww).
values.parameters.description  string Detailed description of the significant weather (only for parameter ww).
values.parameters.icon  string Icon (format png) matching this significant weather (only for parameter ww).
values.parameters.index  object Parameter specific index information
values.parameters.index.index_type  string Unique identifier of the returned weather index.
values.parameters.index.index_name  string Name of the returned weather index.
values.parameters.index.qualification  string Weather index textual representation.
values.parameters.index.description  string Weather index textual assessment.
values.parameters.index.icon  string Parameter level associated icon (if any, otherwise null).
values.parameters.index.color  string Parameter level hexadecimal color code.
values.parameters.index.value  number Parameter level index value (for numeric indexes only, otherwise null).
page object Object containing information about the pagination of the response.
page.totalElements number The total amount of weather values.
page.totalPages number The amount of pages of weather values.
page.pageNumber number The number of the page currently returned.
page.size number The amount of weather values returned per page.

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

Weather forecast

import requests

requests.get("https://api.meersens.com/environment/public/weather/forecast", headers={
  'apikey': 'your_api_key'
}, params={
  lat: 1.234,
  lng: 5.678,
  from: '2021-01-01T00:00:00Z',
  to: '2021-01-02T00:00:00Z',
  page: 0
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/weather/forecast?lat=1.234&lng=5.678&from=2021-01-01T00:00:00Z&to=2021-01-02T00:00:00Z&page=0" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/weather/forecast",{
  params: { 
    lat: 1.234,
    lng: 5.678,
    from: '2021-01-01T00:00:00Z',
    to: '2021-01-02T00:00:00Z',
    page: 0
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "values": [
        {
            "found": true,
            "datetime": "2023-09-05T07:00:00.000Z",
            "index": {
                "index_type": "meersens",
                "index_name": "Meersens",
                "qualification": "Good",
                "icon": null,
                "color": "#6cd2c9",
                "description": "Good atmosphere",
                "value": 14.6,
                "main_pollutants": [
                    "temperature"
                ]
            },
            "parameters": {
                "temperature": {
                    "shortcode": "T",
                    "name": "Temperature",
                    "found": true,
                    "value": 24.4,
                    "unit": "°C",
                    "confidence":5,
                    "index": {
                        "index_type": "meersens",
                        "index_name": "Meersens",
                        "qualification": "Good",
                        "icon": null,
                        "color": "#6cd2c9",
                        "description": "Mild temperature",
                        "value": 14.6
                    }
                },
                "ww": {
                    "shortcode": "WW",
                    "name": "Significant weather",
                    "found": false,
                    "qualification": "Mainly clear",
                    "description": "Clouds dissolving or becoming less developed",
                    "icon": "https://s3.eu-west-2.amazonaws.com/weather.meersens/icons/mainly_clear.png",
                    "confidence": 5,
                    "index": {
                        "index_type": "meersens",
                        "index_name": "Meersens",
                        "qualification": null,
                        "color": "#9A9A9A",
                        "description": null,
                        "value": null
                    }
                },
                "apparent_temperature": {...},
                "humidity": {...},
                "pressure": {...},
                "wind_speed": {...},
                "wind_direction": {...},
                "cloud_cover": {...},
                "precipitations": {...}
            }
        }
        {...}
    ],
    "page": {
        "totalElements": 24,
        "totalPages": 4,
        "pageNumber": 0,
        "size": 6
    }
}

Returns hourly forecast weather data at a given location. For each hour included in the requested timeframe, the parameter value will be retrieved (if found). The maximum timeframe allowed to be requested is 48 hours, meaning 2 days. Each returned page will contain up to 6 time points entries.

Path

GET https://api.meersens.com/environment/public/weather/forecast

Query Parameters

Parameter Type   Description Required
lat number Latitude of the location to compute weather conditions at. In WGS84 format. true
lng number Longitude of the location to compute weather conditions at. In WGS84 format. true
from string ISO_8601 UTC datetime (including timezone) that indicates the starting date of the forecast timeframe data. false
(default:24hours ago)
to string ISO_8601 UTC datetime (including timezone) that indicates the ending date of the forecast timeframe data. false
(default:beginning of current hour)
system string System to be used for parameters units, can be either metric (default) or imperial false
(default: metric)
page number The number of the page to return among the pages of results. false (default: 0)

Response attributes

Parameter Type Description
found  boolean Whether at least one parameter value has been found over the period.
values array Array of hourly weather values.
values.datetime string ISO_8601 UTC datetime indicating the time the data refers to for this hourly entry.
values.index  object Weather index object for this hourly entry.
values.index.index_type  string Unique identifier of the returned weather index.
values.index.index_name  string Name of the returned weather index.
values.index.qualification  string Weather index textual representation.
values.index.description  string Weather index textual assessment.
values.index.icon  string Weather level associated icon (if any, otherwise null).
values.index.color  string Weather level hexadecimal color code.
values.index.value  number Weather level value (for numeric indexes only, otherwise null).
values.index.main_pollutants  array Array of main parameters identifiers.
values.parameters  object Dictionary of available parameters at the requested point for this hourly entry.
values.parameters.shortcode  string Parameter textual shortcode.
values.parameters.name  string Parameter full name.
values.parameters.unit  string Unit in which the parameter value is returned (except for parameter ww).
values.parameters.found  boolean Whether the parameter value has been found.
values.parameters.value  number Value of the parameter in specified unit (except for parameter ww).
values.parameters.confidence  number Parameter value confidence.
values.parameters.qualification  string Textual representation of the significant weather (only for parameter ww).
values.parameters.description  string Detailed description of the significant weather (only for parameter ww).
values.parameters.icon  string Icon (format png) matching this significant weather (only for parameter ww).
values.parameters.index  object Parameter specific index information
values.parameters.index.index_type  string Unique identifier of the returned weather index.
values.parameters.index.index_name  string Name of the returned weather index.
values.parameters.index.qualification  string Weather index textual representation.
values.parameters.index.description  string Weather index textual assessment.
values.parameters.index.icon  string Parameter level associated icon (if any, otherwise null).
values.parameters.index.color  string Parameter level hexadecimal color code.
values.parameters.index.value  number Parameter level index value (for numeric indexes only, otherwise null).
page object Object containing information about the pagination of the response.
page.totalElements number The total amount of weather values.
page.totalPages number The amount of pages of weather values.
page.pageNumber number The number of the page currently returned.
page.size number The amount of weather values returned per page.

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

Weather geographical aggregated conditions

import requests

requests.get("https://api.meersens.com/environment/public/weather/current/aggregate", headers={
  'apikey': 'your_api_key'
}, params={
  code: 69006,
  location_type: 'postal_code',
  iso2_code: 'FR'
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/weather/current/aggregate?code=69006&location_type=postal_code&iso2_code=fr" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/weather/current/aggregate",{
  params: { 
    code: 69006,
    location_type: 'postal_code',
    iso2_code: 'FR'
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "datetime": "2023-04-07T15:00:00.000Z",
    "indexes": {
        "mean": {
            "index_type": "meersens",
            "index_name": "Meersens",
            "qualification": "Correct",
            "icon": null,
            "color": "#44b001",
            "description": "Correct weather",
            "value": 22.51,
            "main_pollutants": [
                "humidity"
            ]
        },
        "min": {
            "index_type": "meersens",
            "index_name": "Meersens",
            "qualification": "Low",
            "icon": null,
            "color": "#029a8d",
            "description": "Cold temperature",
            "value": 20.94,
            "main_pollutants": [
                "temperature"
            ]
        },
        "max": {
            "index_type": "meersens",
            "index_name": "Meersens",
            "qualification": "Correct",
            "icon": null,
            "color": "#44b001",
            "description": "Correct weather",
            "value": 27.42,
            "main_pollutants": [
                "humidity"
            ]
        }
    },
    "parameters": {
        "humidity": {
            "shortcode": "rH",
            "name": "Humidity",
            "unit": "%",
            "found": true,
            "confidence": 5,
            "values": {
                "mean": 73.77,
                "min": 65.47,
                "max": 86.06
            },
            "indexes": {
                "mean": {
                    "index_type": "meersens",
                    "index_name": "Meersens",
                    "qualification": "Correct",
                    "icon": null,
                    "color": "#44b001",
                    "description": "Wet atmosphere",
                    "value": 22.51
                },
                "min": {
                    "index_type": "meersens",
                    "index_name": "Meersens",
                    "qualification": "Correct",
                    "icon": null,
                    "color": "#44b001",
                    "description": "Wet atmosphere",
                    "value": 19.19
                },
                "max": {
                    "index_type": "meersens",
                    "index_name": "Meersens",
                    "qualification": "Correct",
                    "icon": null,
                    "color": "#44b001",
                    "description": "Wet atmosphere",
                    "value": 27.42
                }
            }
        },
        "pressure": {...},
        "temperature": {...},
        "apparent_temperature": {...},
        "wind_speed": {...},
        "wind_direction": {...},
        "precipitations": {...},
        "cloud_cover": {...}
    }
}

Returns current information about weather conditions for a given postal code. The returned results give an overview of the minimum, maximum and average values on the area covered by the specified postal code.

Please note that this is only available for french postal codes so far. As a minimum and maximum wind direction (wind_direction) aggregation would have no sense, wind direction is only aggregated using the mean. Significant weather (ww) is not aggregated.

Path

GET https://api.meersens.com/environment/public/weather/current/aggregate

Query Parameters

Parameter Type   Description Required
code number The postal code of the geographical area to aggregate. true
location_type string The type of the location to apply the aggregation on ("postal_code"). true
iso2_code string The ISO 3166-1 alpha-2 code of the country of the requested postal code. true
system string System to be used for parameters units, can be either metric (default) or imperial false
(default: metric)

Response attributes

Parameter Type Description
found  boolean Whether at least one pollutant value has been found.
datetime string ISO_8601 UTC datetime indicating the time the data refers to.
indexes  object Dictionary of the min, max and mean weather index objects.
indexes.[statistic].index_type  string Unique identifier of the returned weather index.
indexes.[statistic].index_name  string Name of the returned weather index.
indexes.[statistic].qualification  string Weather index textual representation.
indexes.[statistic].description  string Weather index textual assessment.
indexes.[statistic].icon  string Weather level associated icon (if any, otherwise null).
indexes.[statistic].color  string Weather level hexadecimal color code.
indexes.[statistic].value  number Weather level value (for numeric indexes only, otherwise null).
indexes.[statistic].main_pollutants  array Array of main parameters identifiers.
parameters  object Dictionary of available parameters at the requested point.
parameters.shortcode  string Parameter textual shortcode.
parameters.name  string Parameter full name.
parameters.unit  string Unit in which the parameter value is returned.
parameters.found  boolean Whether the parameter value has been found.
parameters.values  object Dictionary of the parameter values statistics in specified unit.
parameters.values.min  number Minimum value of the parameter in specified unit on the requested area.
parameters.values.max  number Maximum value of the parameter in specified unit on the requested area.
parameters.values.mean  number Average value of the parameter in specified unit on the requested area.
parameters.confidence  number Parameter value confidence.
parameters.indexes  object Dictionary of the parameter specific index information statistics over the requested area.
parameters.indexes.[statistic].index_type  string Unique identifier of the returned weather index.
parameters.indexes.[statistic].index_name  string Name of the returned weather index.
parameters.indexes.[statistic].qualification  string Weather index textual representation.
parameters.indexes.[statistic].description  string Weather index textual assessment.
parameters.indexes.[statistic].icon  string Parameter level associated icon (if any, otherwise null).
parameters.indexes.[statistic].color  string Parameter level hexadecimal color code.
parameters.indexes.[statistic].value  number Parameter level index value (for numeric indexes only, otherwise null).

Weather history geographical aggregation

import requests

requests.get("https://api.meersens.com/environment/public/weather/history/aggregate", headers={
  'apikey': 'your_api_key'
}, params={
  code: 69006,
  page: 1,
  location_type: 'postal_code',
  iso2_code: 'FR',
  duration: 'hour',
  from: '2023-06-01T00:00:00Z',
  to: '2023-06-02T00:00:00Z'
})

# With shell, you can just pass the correct header with each request
curl "https://api.meersens.com/environment/public/weather/history/aggregate?code=69006&location_type=postal_code&iso2_code=fr&duration=hour&page=1&from=2023-06-01T00:00:00Z&to=2023-06-02T00:00:00Z" \
  -H "apikey: your_api_key"

const axios = require('axios');

axios.get("https://api.meersens.com/environment/public/weather/history/aggregate",{
  params: { 
    code: 69006,
    location_type: 'postal_code',
    iso2_code: 'FR',
    duration: 'hour',
    page: 1,
    from: '2023-06-01T00:00:00Z',
    to: '2023-06-02T00:00:00Z'
  }
  headers: {'apikey': 'your_api_key'}
})

The above API returns the following JSON structured response:

{
    "found": true,
    "values": [
        {
            "datetime": "2022-06-01T06:00:00.000Z",
            "found": true,
            "indexes": {
                "mean": {
                    "index_type": "meersens",
                    "index_name": "Meersens",
                    "qualification": "Good",
                    "icon": null,
                    "color": "#6cd2c9",
                    "description": "Good atmosphere",
                    "value": 13.23,
                    "main_pollutants": [
                        "temperature"
                    ]
                },
                "min": {
                    "index_type": "meersens",
                    "index_name": "Meersens",
                    "qualification": "Good",
                    "icon": null,
                    "color": "#6cd2c9",
                    "description": "Good atmosphere",
                    "value": 11.54,
                    "main_pollutants": [
                        "humidity"
                    ]
                },
                "max": {
                    "index_type": "meersens",
                    "index_name": "Meersens",
                    "qualification": "Moderate",
                    "icon": null,
                    "color": "#adc704",
                    "description": "Moderate weather",
                    "value": 34.22,
                    "main_pollutants": [
                        "apparent_temperature"
                    ]
                }
            },
            "parameters": {
                "temperature": {
                    "shortcode": "T",
                    "name": "Temperature",
                    "unit": "°C",
                    "found": true,
                    "confidence": 5,
                    "values": {
                        "mean": 23.49,
                        "min": 20.38,
                        "max": 25.83
                    },
                    "indexes": {
                        "mean": {
                            "index_type": "meersens",
                            "index_name": "Meersens",
                            "qualification": "Good",
                            "icon": null,
                            "color": "#6cd2c9",
                            "description": "Mild temperature",
                            "value": 13.23
                        },
                        "min": {
                            "index_type": "meersens",
                            "index_name": "Meersens",
                            "qualification": "Good",
                            "icon": null,
                            "color": "#6cd2c9",
                            "description": "Mild temperature",
                            "value": 8.57
                        },
                        "max": {
                            "index_type": "meersens",
                            "index_name": "Meersens",
                            "qualification": "Good",
                            "icon": null,
                            "color": "#6cd2c9",
                            "description": "Mild temperature",
                            "value": 16.74
                        }
                    }
                },
                "pressure": {...},
                "apparent_temperature": {...},
                "humidity": {...},
                "wind_speed": {...},
                "wind_direction": {...},
                "cloud_cover": {...},
                "precipitations": {...}
            }
        },
        {...}
    ],
  "page": {
    "totalElements": 24,
    "totalPages": 4,
    "pageNumber": 1,
    "size": 6
  }
}

Returns hourly or daily history weather data for a given area or location. For each time point included in the requested timeframe, the minimum, maximum and average parameters concentrationsvalues will be retrieved (if found). Hourly aggregation is only available for a period up to six months ago, and for postal codes. For daily aggregation, it is possible to restrict the data to a specific period of the day: daytime or nighttime.

Please note that this is only available for french postal codes so far As a minimum and maximum wind direction (wind_direction) aggregation would have no sense, wind direction is only aggregated using the mean. Significant weather (ww) is not aggregated.

Path

GET https://api.meersens.com/environment/public/weather/history/aggregate

Query Parameters

Parameter Type   Description Required
location_type string The type of the location to apply the aggregation on ("point" or "postal_code"). true
code number The postal code of the geographical area to aggregate. Required if location_type = "postal_code" false
iso2_code string The ISO 3166-1 alpha-2 code of the country of the requested postal code. Required if location_type = "postal_code" false
lat number The latitude of the point to request daily values for. Required if location_type = "point" false
lng number The longitude of the point to request daily values for. Required if location_type = "point" false
duration string The duration of the temporal aggregation ("day", "daytime", "nighttime" or "hour") false (default: "hour")
from string ISO_8601 UTC datetime (including timezone) that indicates the starting date of the history timeframe data. false
(default:24hours ago)
to string ISO_8601 UTC datetime (including timezone) that indicates the ending date of the history timeframe data. false
(default:beginning of current hour)
page number The number of the page to return among the pages of results. false (default: 0)
system string System to be used for parameters units, can be either metric (default) or imperial false
(default: metric)

Response attributes

Parameter Type Description
found  boolean Whether at least one parameter value has been found over the period.
values array Array of hourly, period or daily weather parameters min, max and mean values.
values.found  boolean Whether at least one parameter value has been found.
values.datetime string ISO_8601 UTC datetime indicating the time the data refers to for this hourly or daily entry. If a specific period (daytime or nighttime) was requested, the datetime represents the day of that period.
values.indexes  object Dictionary of the min, max and mean weather index objects.
values.indexes.[statistic].index_type  string Unique identifier of the returned weather index.
values.indexes.[statistic].index_name  string Name of the returned weather index.
values.indexes.[statistic].qualification  string Weather index textual representation.
values.indexes.[statistic].description  string Weather index textual assessment.
values.indexes.[statistic].icon  string Weather level associated icon (if any, otherwise null).
values.indexes.[statistic].color  string Weather level hexadecimal color code.
values.indexes.[statistic].value  number Weather level value (for numeric indexes only, otherwise null).
values.indexes.[statistic].main_pollutants  array Array of main parameters identifiers.
values.parameters  object Dictionary of available parameters at the requested point for this hourly entry.
values.parameters.shortcode  string Parameter textual shortcode.
values.parameters.name  string Parameter full name.
values.parameters.unit  string Unit in which the parameter value is returned.
values.parameters.found  boolean Whether the parameter value has been found.
values.parameters.values  object Dictionary of the parameter values statistics in specified unit.
values.parameters.values.min  number Minimum value of the parameter in specified unit on the requested area.
values.parameters.values.max  number Maximum value of the parameter in specified unit on the requested area.
values.parameters.values.mean  number Average value of the parameter in specified unit on the requested area.
values.parameters.confidence  number Parameter value confidence.
values.parameters.indexes  object Dictionary of the parameter specific index information statistics over the requested area.
values.parameters.indexes.[statistic].index_type  string Unique identifier of the returned weather index.
values.parameters.indexes.[statistic].index_name  string Name of the returned weather index.
values.parameters.indexes.[statistic].qualification  string Weather index textual representation.
values.parameters.indexes.[statistic].description  string Weather index textual assessment.
values.parameters.indexes.[statistic].icon  string Parameter level associated icon (if any, otherwise null).
values.parameters.indexes.[statistic].color  string Parameter level hexadecimal color code.
values.parameters.indexes.[statistic].value  number Parameter level index value (for numeric indexes only, otherwise null).

Responses

HTTP status Meaning Notes
200  OK Response returned
401 Unauthorized Something is wrong with your api key.
403  Forbidden Either you're requesting an environmental category you do not have access to, or an area outside of your authorized ones.
429  Too many requests You are above your calls quota.

Weather forecast geographical aggregation

Returns hourly forecast weather data at a given location. For each hour included in the requested timeframe, the minimum, maximum and average parameter value will be retrieved (if found).The maximum timeframe allowed to be requested is 48 hours, meaning 2 days. Please refer to the above page for details about the query input and output. Daily aggregation is not supported for forecast data.

Please note that this is only available for french postal codes so far As a minimum and maximum wind direction (wind_direction) aggregation would have no sense, wind direction is only aggregated using the mean. Significant weather (ww) is not aggregated.

Path

GET https://api.meersens.com/environment/public/weather/forecast/aggregate

shell python javascript