Using the Health Alert Zones API

Let’s get started with the API. The API performs reverse look-ups where the input is a set of GPS coordinates which are then translated to information regarding the administrative area or 500×500 tile that these inputted coordinates are within. We will take you through some of the functionalities of the API step by step. If your questions aren’t answered on this site, please contact us.

In our examples, we will use Curl. If you’re on Linux or OS X, you already have it installed. Windows users can get it here.
You can simply copy and paste the examples, but you will need to replace certain values with information that applies to your specific situation.

Getting started

GET YOUR FREE API KEY

First of all, you need to get some credentials. With an API key you will be able to access the related API and if applicable your usage will be automatically tracked and billed. Just click on the “GET YOUR FREE API KEY” button above, to apply for a free trial. Your API key will be between 30 and 128 characters long.

For purchasing you can go to our pricing table, and select your preferred shirt size model and make your credit card payment via our provider Stripe.

Getting covid-19 data

The first implementation of this API focused on the COVID-19 pandemic.

First of all, an API key (token) is required, and can be assigned to the ‘x-api-key’.

curl -X GET
  https://api.and.com/covidv1/endpoint?args
  -H 'accept: application/json' 
  -H 'x-api-key: {token}' 
  -H 'cache-control: no-cache' 
  -H 'content-type: application/json'

If the API token is incorrect you will receive {"message":"Forbidden"}

Retrieving the country list

https://api.and.com/covidv1/countries/list

Gives you a json containing a list of (name, country dial code, country iso 3 code) to be used with other API
end points.

The result will look as the following example:

{
  "codes": [
    {
      "ISO3": "MLI",
      "name": "Mali;MLI",
      "dial_code": "223"
    },
    {
      "ISO3": "NER",
      "name": "Niger;NER",
      "dial_code": "227"
    },
    {
      "ISO3": "NGA",
      "name": "Nigeria;NGA",
      "dial_code": "234"
    },
    {
      "ISO3": "TZA",
      "name": "Tanzania;TZA",
      "dial_code": "255"
    },
    {
      "ISO3": "ZMB",
      "name": "Zambia;ZMB",
      "dial_code": "260"
    },
 }

Retrieving country information

1. country2data

https://api.and.com/covidv1/country2data?country={country iso3 code}&admin={admin}

Country code and admin level are required. Country code is a iso3 code from countries/list. Admin is between 0 and 8. Returns a json containing a timestamp and data, data is a list of dictionaries containing data of interest for all administration of a given country at a given level.

Where for ‘admin’ you can fill in:

  • admin0 : Admin 0 boundaries contain the highest administrative level in the hierarchy: the country
  • admin1, admin2, ... , admin7 : Admin 1-7 boundaries contain smaller administrative divisions which per layer cover the complete country
  • admin8 : Admin 8 boundaries contain the lowest administrative level in the hierarchy. In most cases, the municipalities are included at this level.

A list of all available administrative levels per country, can be found here.

 

The result contains info regarding the administrative boundaries that were found:

covid_trend: itrend of the covid-19 confirmed cases in the requested region. value is a positive/negative decimal number.
covid_deceased_trend: trend of the covid-19 deceased people in the requested region. value is a positive/negative decimal number.
business_density: the business density for the requested region. value is a positive decimal number > 0.
covid_risk_score: the covid-19 risk score for the requested region. This value is calculated by AND based on the COVID-19 numbers and the business density a.o., and is a positive decimal number > 0.
trend_days: Number of days related to the trend. E.g. if trend_days=1 and covid_trend=10, that means that there has been an increment of 10 cases w.r.t. the last day, wich is the date_reported – trend_days.
date_reported: day related to the provided covid data

The result will look as the following example:

{
  "data": [
    {
      "covid_deceased_trend": 30,
      "business_density": "3",
      "total_deaths": 8830,
      "name": "Germany;DEU",
      "covid_risk_score": "3.4",
      "date_reported": "2020-06-17",
      "covid_trend": 345,
      "country_code": "49",
      "total_cases": 187184,
      "boundary_id": "Germany;DEU",
      "trend_days": 1,
      "category_code": 900,
      "category_name": "admin0",
      "country_name": "Germany;DEU"
    }
  ],
  "timestamp": "2020-06-18T08:51:03.960103+00:00"
}

2. xy2data

https://api.and.com/covidv1/xy2data?x={x}&y={y}&admin={admin}

X is the longitude, required.
Y is the latitude, required.
Admin is the administration level, required.

Given the coordinates and the administration level will return data of interest for the administration that was found at these coordinates. Given that most low level coordinates are likely to have less data than higher ones (at least for covid data), data of interest for upper level administrations starting from the one which was found are also returned. Data is in json format. Keys that would be mapped to null are removed. In the hierarchy_data, p0 stands for the current administration level, p1 from the administration above that, and so on. Thus p0 and upwards will contain different data (admin levels) based on what country or admin level you are querying for.

The result will look as the following example:

{
  "hierarchy_data": {
    "p3": {
      "country_name": "Germany;DEU",
      "total_cases": 187184,
      "business_density": "3",
      "name": "Germany;DEU",
      "date_reported": "2020-06-17",
      "country_code": "49",
      "total_deaths": 8830,
      "category_name": "admin0",
      "covid_deceased_trend": 30,
      "boundary_id": "Germany;DEU",
      "category_code": 900,
      "covid_risk_score": "3.3",
      "trend_days": 1,
      "covid_trend": 345
    },
    "p2": {
      "country_name": "Germany;DEU",
      "total_cases": 3362,
      "business_density": "4",
      "name": "Brandenburg;BB",
      "date_reported": "2020-06-16",
      "country_code": "49",
      "total_deaths": 163,
      "category_name": "admin1",
      "boundary_id": "Germany;DEU|Brandenburg;BB",
      "category_code": 901,
      "covid_risk_score": "4.4",
      "trend_days": 1,
      "covid_trend": 28
    },
    "p1": {
      "country_name": "Germany;DEU",
      "total_cases": 565,
      "business_density": "6",
      "name": "Potsdam-Mittelmark;PM",
      "date_reported": "2020-06-15",
      "country_code": "49",
      "total_deaths": 35,
      "category_name": "admin2",
      "boundary_id": "Germany;DEU|Brandenburg;BB|Potsdam-Mittelmark;PM",
      "category_code": 902,
      "covid_risk_score": "3.7",
      "trend_days": 1,
      "covid_trend": 9
    },
    "p0": {
      "country_name": "Germany;DEU",
      "boundary_id": "Germany;DEU|Brandenburg;BB|Potsdam-Mittelmark;PM|Beetzsee",
      "business_density": "4",
      "category_code": 908,
      "name": "Beetzsee",
      "covid_risk_score": "3.7",
      "country_code": "49",
      "category_name": "admin8"
    }
  },
  "timestamp": "2020-06-18T09:11:34.324187+00:00"
}

Retrieving 500×500 tile information

1. xy2tile

https://api.and.com/covidv1/xy2tile?x={x}&y={y}&zoom={zoom}

This is the first endpoint of the tile system, based on web mercator tiles. The world is divided into tiles, each zoom level is a different layer/level of tiles. At zoom level 0, the world is a single (2^0) tile, at zoom level 1 the world is made of 2×2 tiles (2^1 each side), etc. Note that these square tiles will have a different size based on their latitude.

X is the longitude, required.
Y is the latitude, required.
Zoom is the zoom level, currently between 14 and 20 (included), required.

Given the arguments, a geojson containing the geometry of the found tile and data of interest for the administration that the tile is part of will be returned. Data of interest related to the administrations is presented in the same format as the previously mentioned hierarchy_data.

Among the properties you will find the x_index and y_index of the tile, representing the indexes of the tile at the given zoom level (indexes go from 0 to (2^zoom -1). This API endpoint can serve as the first way of finding out in which tile (and thus indexes) a given gps/coordinate/person is.

The result will look as the following example:

{
  "features": [
    {
      "geometry_name": "geometry",
      "id": "null",
      "geometry": {
        "coordinates": [
          [
            [
              12.513427734375,
              52.5162208639307
            ],
            [
              12.513427734375,
              52.5229059402781
            ],
            [
              12.5244140625,
              52.5229059402781
            ],
            [
              12.5244140625,
              52.5162208639307
            ],
            [
              12.513427734375,
              52.5162208639307
            ]
          ]
        ],
        "type": "Polygon",
        "bbox": [
          12.513427734375,
          52.516220863930734,
          12.5244140625,
          52.522905940278065
        ]
      },
      "properties": {
        "hierarchy_data": {
          "p3": {
            "country_name": "Germany;DEU",
            "total_cases": 187184,
            "business_density": "6",
            "name": "Germany;DEU",
            "date_reported": "2020-06-17",
            "country_code": "49",
            "total_deaths": 8830,
            "category_name": "admin0",
            "covid_deceased_trend": 30,
            "boundary_id": "Germany;DEU",
            "category_code": 900,
            "covid_risk_score": "4.8",
            "trend_days": 1,
            "covid_trend": 345
          },
          "p2": {
            "country_name": "Germany;DEU",
            "total_cases": 3362,
            "business_density": "4",
            "name": "Brandenburg;BB",
            "date_reported": "2020-06-16",
            "country_code": "49",
            "total_deaths": 163,
            "category_name": "admin1",
            "boundary_id": "Germany;DEU|Brandenburg;BB",
            "category_code": 901,
            "covid_risk_score": "3.3",
            "trend_days": 1,
            "covid_trend": 28
          },
          "p1": {
            "country_name": "Germany;DEU",
            "total_cases": 565,
            "business_density": "5",
            "name": "Potsdam-Mittelmark;PM",
            "date_reported": "2020-06-15",
            "country_code": "49",
            "total_deaths": 35,
            "category_name": "admin2",
            "boundary_id": "Germany;DEU|Brandenburg;BB|Potsdam-Mittelmark;PM",
            "category_code": 902,
            "covid_risk_score": "5",
            "trend_days": 1,
            "covid_trend": 9
          },
          "p0": {
            "country_name": "Germany;DEU",
            "boundary_id": "Germany;DEU|Brandenburg;BB|Potsdam-Mittelmark;PM|Beetzsee",
            "business_density": "6",
            "category_code": 908,
            "name": "Beetzsee",
            "covid_risk_score": "4.8",
            "country_code": "49",
            "category_name": "admin8"
          }
        },
        "y_index": 10746,
        "business_density": "3",
        "x_index": 17523,
        "covid_risk_score": "3.3"
      },
      "type": "Feature"
    }
  ],
  "totalFeatures": 1,
  "timestamp": "2020-06-18T09:19:12.496499+00:00",
  "numberMatched": 1,
  "crs": {
    "properties": {
      "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
    },
    "type": "name"
  },
  "type": "FeatureCollection",
  "numberReturned": 1,
  "bbox": [
    12.513427734375,
    52.5162208639307,
    12.5244140625,
    52.5229059402781
  ]
}

2. index2tile

https://api.and.com/covidv1/index2tile?x={x index}&y={y index}&zoom={zoom}

This is the second endpoint of the tile system, which can serve as a way of collecting tiles around a given known tile (ideally retrieved with xy2tile).

X is the x index of the tile, required.
Y is the y index, required.
Zoom is the zoom level, currently between 14 and 20 (included).

Given the arguments, a geojson containing the geometry of the found tile and data of interest for the administration that the tile is part of will be returned. The returned geojson is equal to the geojson returned by xy2tile.