# DeFROST Overview

Get a glimpse of how to integrate DeFROST in your website or mobile app.

You can integrate snow data from DeFROST in two main ways:

### DeFROST Maps

The DeFROST Maps allow you to **display snow cover and depth as a map** and integrates quickly with the most popular mobile & web mapping frameworks. Maps are delivered via the **Tiled Map Service** standard and allows you to customize the look and feel of the tiles on the fly.&#x20;

![DeFROST Global Snow Map near Vancouver, depicting snow depth on 20th December 2019.](https://1127025084-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Lili0IfPABv5Bgn32Kc%2F-LwY8uiB5kLVssTlw_zP%2F-LwYEeoxR0KCpHoqqiK4%2FVancouver-20.12.2019.png?alt=media\&token=6f45d256-c2b1-4208-88f7-4b03a446b61f)

You can read through our [quickstart](https://docs.defrost.io/introduction/development-quickstart) to get started with **Leaflet**, **Mapbox**, **OpenLayers and Google Maps***.* Check the [DeFROST Maps section](https://docs.defrost.io/#defrost-maps) for an in-depth introduction to the two different snow maps offered: the [European Alps map](https://docs.defrost.io/defrost-maps/european-alps-map) or the [Global map](https://docs.defrost.io/defrost-maps/global-map).

### DeFROST API

Do you want to power a custom, more advanced use case? [DeFROST API](https://defrost.io/api-docs) lets you **query snow data for a point, along a path or over an area programmatically**. Check below for a quick example on a query to find out whether or not there is snow at the top of the Matterhorn:

## snow-point

<mark style="color:blue;">`GET`</mark> `https://api.defrost.io/v1/snow-point/{lat}/{lng}`

Obtain the latest snow status data for a specific coordinate expressed in latitude and longitude degrees.

#### Path Parameters

| Name | Type   | Description                   |
| ---- | ------ | ----------------------------- |
| lat  | number | Latitude measured in degrees  |
| lng  | number | Longitude measured in degrees |

{% tabs %}
{% tab title="200 In this example, DeFROST returns a snow-positive reply for the Matterhorn summit last sensed by a satellite on 19th August 2019 at 12:15 UTC." %}

```javascript
{
    "lat": 45.9766,
    "lng": 7.6585, 
    "snow": true,
    "depth": 1,
    "date": "2019-08-19T12:15:00Z",
}
```

{% endtab %}
{% endtabs %}

The DeFROST API is a **RESTful API compliant with the OpenAPI 2.0** standard, so it can be integrated easily in your application.  As such you can use it in any environment connected to the world wide web using a TCP/IP library of your choice.  The **response data format is in the JSON format**, which is widely supported by all major programming languages and frameworks. That means you can integrate the API in most platforms including all major **web browsers**, **Android**, **iOS**, **Python, C/C++, Node.js**. You name it.&#x20;

{% hint style="info" %}
To get started in minutes with either DeFROST Maps or API, read the [Development Quickstart](https://docs.defrost.io/introduction/development-quickstart).
{% endhint %}


# Use Cases

Here are a few sample cases in which you can use our API to enhance your application.

### Safety first: detect slippery terrain

Slippery terrain due to wet or icy snow provoke too many fatal and non-fatal accidents outdoors. Help your users avoid dangerous terrain. You can use DeFROST API to [query various coordinates](https://defrost.io/api-docs#operation/Snow%20cover%20at%20point) to test the presence of snow, e.g. over a hiking trail. When combined with other data such as elevation, you will be able to detect steep and snowy terrain which shall be avoided!

### Find the right trail for the right activity

Is your user searching for trails to hike or trails to snowshoe? Whether the perfect trail shall be snowy or snow-free, you can propose the right trail for an activity by using DeFROST API to query the presence of snow over a set of coordinates. Define how much snow coverage is needed and filter out trails that do not match your user's criteria!

### Alert on snow coverage changes

Your users are planning outdoor activities ahead of time, but snow coverage changes every day. Actively notify your users of important snow coverage changes that might prevent them from having an enjoyable and safe experience outdoors. Even better, propose a more appropriate alternative together with your alert!

### Tackle seasonality

Most people enjoy the outdoors during the peak summer and winter seasons; however, though unpredictable and variable, autumn and spring can offer ideal snow and snow-free conditions. Use DeFROST API to adapt yourself daily to your region of interest's status, deploying dynamic marketing campaigns when outdoor conditions are ideal. Keep growing even off-season!


# Development Quickstart

Get up and running with our Snow Cover API & Maps and kick-start your DeFROST integration.

Integrating DeFROST in your apps can begin right after you create a DeFROST account, and in just three simple steps:

1. Obtain your API tokens
2. Make a test API Request
3. Display the snow cover map layer

{% hint style="info" %}
All the source code snippets used in this guide are available in the [DeFROST Code Examples GitHub repository](https://github.com/wegaw/defrost-examples), which allows you to **kick-start a working project with just two commands**.
{% endhint %}

Read below for a step by step guide:

### Step 1: Obtain your API tokens

To use DeFROST, you'll need an access token. We use this token to associate any of your requests to your account. Find your token or refresh it in your [Account Dashboard](https://dashboard.defrost.io) page or obtain it programmatically using the [Create Token API endpoint](https://defrost.io/api-docs#operation/Create%20token).

You will obtain two tokens:

* An Access Token, allowing you to make any API or Maps request
* A Refresh Token, allowing you to obtain a new Access Token when this expires

{% hint style="info" %}
To increase the security of your account, Access tokens **automatically expire** after 7 days, while Refresh tokens expire after 10 days.&#x20;
{% endhint %}

Due to automated expiration of both tokens, you need to implement your integration taking this aspect into account. An expired Access Token will return an HTTP response code `401 Unauthorized`, a signal for you to use the [Refresh Token API endpoint](https://defrost.io/api-docs#operation/Refresh%20token) to obtain a newly valid Access Token. If the Refresh Token is expired, obtain a new pair of tokens via the [Create Token API endpoint](https://defrost.io/api-docs#operation/Create%20token).&#x20;

The tokens are standard [JSON Web Tokens](https://jwt.io/). Their payload contain the expiration date, which allows you to easily test whether a token is expired or not:

{% code title="check-refresh-token-expired.js" %}

```javascript
var access_or_refresh_token = '<YOUR_ACCESS_OR_REFRESH_TOKEN>';
return JWTDecode(access_or_refresh_token).exp < Date.now() / 1000;
```

{% endcode %}

### Step 2: Make a test API Request

To test that you are ready to start integrating with DeFROST API, make a test API request using your secret API Access and Refresh tokens to refresh the Access token or retrieve the available snow covers.

{% hint style="warning" %}
Make sure to modify the snippets with your API tokens obtained in the step above
{% endhint %}

{% tabs %}
{% tab title="curl" %}
{% code title="defrost\_test.sh" %}

```bash
# URLs used in this example
export API_URL="https://api.defrost.io/v1/snow-covers/"
export REFRESH_URL="https://api.defrost.io/v1/token/refresh/"
# Your DeFROST API tokens
export JWT_ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export JWT_REFRESH_TOKEN="<YOUR_REFRESH_TOKEN>"

# This is how you would refresh your access token
JWT_ACCESS_TOKEN=`curl -X POST -F "refresh=$JWT_REFRESH_TOKEN" "$REFRESH_URL" | sed -E "s/\{\"access\":\"(.+?)\"\}/\1/gI"`
echo "Your new access token is $JWT_ACCESS_TOKEN"
# Let's make an API call using the new token
DATA=`curl --header "Authorization: Bearer $JWT_ACCESS_TOKEN" "$API_URL"`
echo "DATA RECEIVED: $DATA"
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code title="defrost\_test.py" %}

```python
import requests

# URLs used in this example
SAMPLE_API_URL = 'https://api.defrost.io/v1/snow-covers/'
TOKEN_REFRESH_URL = 'https://api.defrost.io/v1/token/refresh/'
# Your DeFROST API tokens
JWT_ACCESS_TOKEN = '<YOUR_ACCESS_TOKEN>'
JWT_REFRESH_TOKEN = '<YOUR_REFRESH_TOKEN>'

session = requests.Session()
# This is how you would refresh your access token
r = session.post(TOKEN_REFRESH_URL, data = {'refresh': JWT_REFRESH_TOKEN}, timeout=300)
if r.status_code == 200:
    JWT_ACCESS_TOKEN = r.json()['access']
    print('Your new access token is ', JWT_ACCESS_TOKEN)

# Let's make an API call using the new token
headers = {'Authorization': 'Bearer ' + JWT_ACCESS_TOKEN}
r = session.get(SAMPLE_API_URL, headers=headers, timeout=300)
if r.status_code == 200:
    data = r.json()
    print('Data retrieved', data)
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code title="defrost\_test.js" %}

```javascript
// In this example we will use the axios package to make API requests
// Make sure you import axios. In this example we do it with bundles.
// You could also get axios by including the following in your HTML head
// <script src="https://unpkg.com/axios/dist/axios.min.js"></script>
// Or in Node: const axios = require('axios');
import axios from 'axios';

// URLs used in this example
let SAMPLE_API_URL = 'https://api.defrost.io/v1/snow-covers/';
let TOKEN_REFRESH_URL = process.env.TOKEN_REFRESH_URL;
// Your DeFROST API tokens
let JWT_ACCESS_TOKEN = '<YOUR_ACCESS_TOKEN>';
let JWT_REFRESH_TOKEN = '<YOUR_REFRESH_TOKEN>';

(async() => {
    // if necessary, this is how you would refresh your access token
    let response = await axios.post(TOKEN_REFRESH_URL, {
        refresh: JWT_REFRESH_TOKEN;
    })

    if(response.status == 200) {
        console.info('Your new access token is ', response.data['access']);
        JWT_ACCESS_TOKEN = response.data['access']; 
    }

    // make sure you always include your access token in every request
    axios.interceptors.request.use( config => {
        config.headers.Authorization = 'Bearer ' + JWT_ACCESS_TOKEN;
        return config;
    }, error => {
        return Promise.reject(error);
    })

    // now you are ready to make an API call
    response = await axios.get(SAMPLE_API_URL);
    if( response.status == 200) {
        console.info(response.statusText,'(',response.status,') ',response.data);
    }
    return response.status;
})();
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Step 3: Display the snow cover map layer

{% hint style="info" %}
The code examples here are using the DeFROST [European Alps Map](https://docs.defrost.io/defrost-maps/european-alps-map). Check the [Global Map section](https://docs.defrost.io/defrost-maps/global-map) if you are looking for coverage beyond this region.
{% endhint %}

To test that your integration with DeFROST Maps is working correctly, use the examples below for your web mapping library of choice. We provide examples for the most popular web mapping libraries: [OpenLayers](http://openlayers.org), [Leaflet](https://leafletjs.com/), [Mapbox](https://www.mapbox.com/) and [Google Maps](https://developers.google.com/maps/documentation/javascript/tutorial).

#### Google Maps users: whitelist your HTTP referrers

Using the DeFROST API, you can [**add as many HTTP referrers as you want to your whitelist**](https://defrost.io/api-docs#tag/Domain-whitelist) - exclusively allowing requests from such referrers to use your tokens and DeFROST services. This is an added security layer that, while recommended for all cases, it is only **mandatory for Google Maps users**. Since this library does not support sending your token in each tile request's authorization header, you need to send it via a query parameter - making your token exposed.

{% hint style="warning" %}
Make sure to modify the snippets below with your API access token. The Mapbox snippet requires, in addition, your Mapbox token.
{% endhint %}

{% tabs %}
{% tab title="OpenLayers" %}
{% code title="defrost-ol-map.html" %}

```markup
<!doctype html>
<html lang="en">
<meta charset="UTF-8">

<head>
    <script src="https://cdn.rawgit.com/openlayers/openlayers.github.io/master/en/v5.3.0/build/ol.js"></script>
    <link rel="stylesheet" href="https://cdn.rawgit.com/openlayers/openlayers.github.io/master/en/v5.3.0/css/ol.css" type="text/css">
    <style>
        html, body {
            margin: 0;
            height: 100%;
        }

        #map {
            height: 100%;
            width: 100%;
        }
    </style>
    <title>DeFROST OpenLayers example</title>
</head>

<body>
    <div id="map"></div>
    <script type="text/javascript">
        var token = '<YOUR_ACCESS_TOKEN>';
        var defrost_maps_url = 'https://maps.defrost.io/{z}/{x}/{y}.png';
        
        var map = new ol.Map({
            target: 'map',
            layers: [
                new ol.layer.Tile({
                    source: new ol.source.OSM()
                }),
                new ol.layer.Tile({
                    source: new ol.source.XYZ({
                        url: defrost_maps_url,
                        tileLoadFunction: (tile, src) => {
                            var client = new XMLHttpRequest();
                            client.open('GET', src);
                            client.responseType = "arraybuffer";
                            client.setRequestHeader("Authorization", "Bearer " + token);
                            client.onload = function () {
                                var arrayBufferView = new Uint8Array(this.response);
                                var blob = new Blob([arrayBufferView], { type: 'image/png' });
                                var urlCreator = window.URL || window.webkitURL;
                                var imageUrl = urlCreator.createObjectURL(blob);
                                tile.getImage().src = imageUrl;
                            };
                            client.send();
                        },
                        crossOrigin: 'anonymous',
                        attributions: 'Snow data &copy; <a href="https://www.defrost.io/">WeGaw Ltd.</a>',
                    }),
                    opacity: 0.3
                })
            ],
            view: new ol.View({
                center: ol.proj.fromLonLat([7.7491, 46.0207]),
                zoom: 12
            })
        });
    </script>
</body>

</html>
```

{% endcode %}
{% endtab %}

{% tab title="Leaflet" %}
{% code title="defrost-leaflet-map.html" %}

```markup
<!doctype html>
<html lang="en">
<meta charset="UTF-8">

<head>
    <script src="https://unpkg.com/leaflet@1.5.1/dist/leaflet.js"></script>
    <link rel="stylesheet" href="https://unpkg.com/leaflet@1.5.1/dist/leaflet.css" type="text/css">
    <style>
        html, body {
            margin: 0;
            height: 100%;
        }

        #map {
            height: 100%;
            width: 100%;
        }
    </style>
    <title>DeFROST Leaflet example</title>
</head>

<body>
    <div id="map"></div>
    <script type="text/javascript">
        var token = '<YOUR_ACCESS_TOKEN>';
        var defrost_maps_url = 'https://maps.defrost.io/{z}/{x}/{y}.png';
        
        L.TileLayer.headers = L.TileLayer.extend({
            createTile(coords, done) {
                var tile = document.createElement('img');

                L.DomEvent.on(tile, 'load', L.Util.bind(this._tileOnLoad, this, done, tile));
                L.DomEvent.on(tile, 'error', L.Util.bind(this._tileOnError, this, done, tile));

                if (this.options.crossOrigin || this.options.crossOrigin === '') {
                    tile.crossOrigin = this.options.crossOrigin === true ? '' : this.options.crossOrigin;
                }

                /*
                Alt tag is set to empty string to keep screen readers from reading URL and for compliance reasons
                http://www.w3.org/TR/WCAG20-TECHS/H67
                */
                tile.alt = '';

                /*
                Set role="presentation" to force screen readers to ignore this
                https://www.w3.org/TR/wai-aria/roles#textalternativecomputation
                */
                tile.setAttribute('role', 'presentation');

                // Custom code to query tiles using Bearer Authentication headers 
                var url = this.getTileUrl(coords);
                var client = new XMLHttpRequest();
                client.open('GET', url);
                client.responseType = "arraybuffer";
                client.setRequestHeader("Authorization", "Bearer " + token);
                client.onload = function () {
                    var arrayBufferView = new Uint8Array(this.response);
                    var blob = new Blob([arrayBufferView], { type: 'image/png' });
                    var urlCreator = window.URL || window.webkitURL;
                    var imageUrl = urlCreator.createObjectURL(blob);
                    tile.src = imageUrl;
                    done(null, tile);
                };
                client.send();

                return tile;
            }
        });
        L.tileLayer.headers = (url, options) => new L.TileLayer.headers(url, options);

        map = L.map('map').setView([46.0207, 7.7491], 12);

        L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
            attribution: 'Map data &copy; <a href="https://www.openstreetmap.org/">OpenStreetMap</a> contributors',
        }).addTo(map);

        // Notice 
        L.tileLayer.headers(defrost_maps_url, {
            attribution: 'Snow data &copy; <a href="https://www.defrost.io/">WeGaw Ltd.</a>',
            crossOrigin: 'anonymous',
            opacity: 0.3
        }).addTo(map);
    </script>
</body>

</html>
```

{% endcode %}
{% endtab %}

{% tab title="Mapbox" %}
{% code title="defrost-mapbox-map.html" %}

```markup
<!doctype html>
<html lang="en">
<meta charset="UTF-8">

<head>
    <script src='https://api.tiles.mapbox.com/mapbox-gl-js/v1.2.0/mapbox-gl.js'></script>
    <link href='https://api.tiles.mapbox.com/mapbox-gl-js/v1.2.0/mapbox-gl.css' rel='stylesheet' />
    <style>
        html, body {
            margin: 0;
            height: 100%;
        }

        #map {
            height: 100%;
            width: 100%;
        }
    </style>
    <title>DeFROST Mapbox example</title>
</head>

<body>
    <div id="map"></div>
    <script type="text/javascript">
        var token = '<YOUR_ACCESS_TOKEN>';
        var defrost_maps_url = 'https://maps.defrost.io/{z}/{x}/{y}.png';
        mapboxgl.accessToken = '<YOUR_MAPBOX_TOKEN>';
        
        var map = new mapboxgl.Map({
            container: 'map',
            style: 'mapbox://styles/mapbox/streets-v11',
            center: [7.7491, 46.0207],
            zoom: 11,
            transformRequest: (url, resourceType) => {
                if (resourceType === 'Tile' && url.startsWith(defrost_maps_url.split('/{z}/{x}/{y}.png')[0])) {
                    return {
                        url: url,
                        headers: { 'Authorization': 'Bearer ' + token },
                    }
                }
            }
        });

        map.on('load', function(){
            var dfTileLayer = {
                "id": 'df',
                "type": "raster",
                "source": {
                    "type": "raster",
                    "tiles": [defrost_maps_url,],
                    "tileSize": 256,
                    "maxzoom": 13
                },
                "paint": {
                    "raster-opacity": 0.3,
                    "raster-resampling": "linear"
                }
            };
            this.addLayer(dfTileLayer);
        });
    </script>
</body>

</html>
```

{% endcode %}
{% endtab %}

{% tab title="Google Maps" %}
{% code title="google-map.html" %}

```markup
<!doctype html>
<html lang="en">
<meta charset="UTF-8">

<head>
    <style>
        html, body {
            margin: 0;
            height: 100%;
        }

        .map {
            height: 100%;
            width: 100%;
        }
    </style>
    <title>DeFROST Google Maps example</title>
</head>

<body>
    <div id="map" class="map"></div>
    <script type="text/javascript">
        var token = '<YOUR_ACCESS_TOKEN>';
        var defrost_maps_url = 'https://maps.defrost.io/{z}/{x}/{y}.png';

        function initMap(){
            map = new google.maps.Map(document.getElementById('map'), {
                center: {lat: 46.0207, lng: 7.7491}, 
                zoom: 12
            });

            // Name the layer anything you like.
            var layerID = 'defrost_alps_snow';

            // Attention: Google Maps JS API does not allow to set an Authorization header
            // in each tile request. We are therefore forced to set the token as a query parameter.
            // BEWARE: this has an increased security risk, as the token is exposed. This is why it is
            // mandatory to whitelist the domains from which you will use it. 
            // Check https://defrost.io/api-docs#tag/Domain-whitelist to learn how.
            // Take into account that this demo will not work by simply opening the HTML file, since no
            // "Referrer" header will be set in the requests in that way.
            defrost_maps_url = defrost_maps_url + '?token=' + token;
            // Create a new ImageMapType layer.
            var layer = new google.maps.ImageMapType({
                name: layerID,
                getTileUrl: function(coord, zoom) {
                    var url = defrost_maps_url
                    .replace('{x}', coord.x)
                    .replace('{y}', coord.y)
                    .replace('{z}', zoom);
                    return url;
                },
                tileSize: new google.maps.Size(256, 256),
                minZoom: 1,
                maxZoom: 20,
                isPng: true,
                opacity: 0.30
            });

            // Register the new layer, then activate it.
            map.overlayMapTypes.push(layer);
        }
        
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=<YOUR_GMAPS_API_KEY>&callback=initMap"
    async defer></script>
</body>

</html>
```

{% endcode %}
{% endtab %}
{% endtabs %}

The key point to keep in mind is that DeFROST Maps requires Bearer token Authentication. This forces libraries displaying tile layers to **include the appropriate Authentication header in each tile request**. While Mapbox supports this method out of the box, OpenLayers and Leaflet require a minor workaround: have a look in the examples above. In the special case of Google Maps, you have no option but to send the token as a query parameter, which forces you to [add any HTTP Referrer to your whitelist](https://defrost.io/api-docs#tag/Domain-whitelist).

### Next steps

You are now ready to integrate DeFROST! You can check the following additional resources:

{% hint style="success" %}
[Code Examples GitHub repository](https://github.com/wegaw/defrost-examples):  Full source code and starter project demonstrating integration of DeFROST Maps and API in supported platforms.&#x20;
{% endhint %}


# Maps Overview

Integrate snow maps in your web mapping application

DeFROST currently offers **two different snow maps**: one covering the [European Alps](https://docs.defrost.io/defrost-maps/european-alps-map) and the other  covering [the entire globe](https://docs.defrost.io/defrost-maps/global-map). Both maps display the snow depth in centimeters.

The table below quickly summarizes both maps' main characteristics:

|                            | [**European Alps Map**](https://docs.defrost.io/defrost-maps/european-alps-map) | [**Global Map**](https://docs.defrost.io/defrost-maps/global-map) |
| -------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Spatial resolution**     | 20 meters                                                                       | 375 meters                                                        |
| **Update time**            | Daily at 3AM CET                                                                | Daily at 4PM CET                                                  |
| **Tile zoom levels**       | 13 zoom levels                                                                  | 9 zoom levels                                                     |
| **Tile size**              | 256x256 pixels                                                                  | 256x256 pixels                                                    |
| **Snow depth color range** | <p>Light blue (#35e9e6)<br>to Bright pink (#ff01fb)</p>                         | <p>Light blue (#35e9e6)<br>to Bright pink (#ff01fb)</p>           |
| **Covered area**           | Alpine Convention                                                               | 66.5°N to 66.5°S                                                  |

Both maps are **served via their own** [**Tile Map Service**](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames) **(TMS) based XYZ tiles endpoint**, making it easy to display it as a layer on top of a basemap of choice, with any of the major web mapping libraries available today such as OpenLayers, Leaflet or Mapbox.&#x20;

### Map Legend

You can use the image below in your application so your users can interpret the snow depth seen on the map. Or feel free to use the JSON definition to programmatically display the range.

![](https://1127025084-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Lili0IfPABv5Bgn32Kc%2F-LwY0J_p2dGjo-0NUAFa%2F-LwY6OGG7CV730HrZDie%2Fdepth-scale.png?alt=media\&token=dca2c71f-fe78-44fb-9020-9effa4838b8a)

{% file src="/files/-M-oW3wEeX40a80xmhKy" %}
JavaScript Definition of Snow Depth Range
{% endfile %}

### Maps Authentication: JSON Web Tokens

In the same way as the DeFROST API, access to the Maps is protected using the [JSON Web Tokens (JWT)](https://jwt.io/) industry standard. This means that **any request to the XYZ tile endpoints must be authenticated by passing a valid JWT token in the HTTP Authorization request header**.

{% hint style="info" %}
Check the [Obtain your API tokens section](https://docs.defrost.io/introduction/development-quickstart#step-1-obtain-your-api-tokens) in the Development Quickstart for important details on DeFROST's Authentication functioning, applying to both the API and Maps.
{% endhint %}

JWT is a highly secure, modern but relatively recent way of securing the access to a Tile Server, making it neccessary to write additional code in order to make it work with some web mapping libraries such as OpenLayers or Leaflet. The Mapbox library already supports JWT authentication method easily out of the box. However - **we have already made that work for you**:

{% hint style="success" %}
You can **check working code examples** on either OpenLayers, Leaflet or Mapbox in the [Development Quickstart](https://docs.defrost.io/introduction/development-quickstart) section or the [example project](https://github.com/wegaw/defrost-examples).
{% endhint %}


# European Alps Map

Daily updated snow cover map at 20 meters resolution

The Alps are the highest and most extensive mountain range system that lies entirely in Europe, and stretching approximately 1,200 kilometres across eight Alpine countries: France, Switzerland, Monaco, Italy, Liechtenstein, Austria, Germany, and Slovenia.

![The DeFROST Map for the European Alps coverage area, as per the Alpine Convention](https://1127025084-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Lili0IfPABv5Bgn32Kc%2F-LsbFGhrDoNmBDS0TprD%2F-LsbG6PG-Q_572jDxpfJ%2FAlpine_higher_respng.png?alt=media\&token=1cc1b4af-7c45-4af0-b4c4-988abd825472)

Due to the key importance of this area in Europe and globally in terms of population, visitors and human activity, DeFROST operates and serves a daily snow cover map with 20 meters resolution for its extent.

{% hint style="warning" %}
If you make any request for a tile outside the above covered area, the DeFROST server will return a 404 Not Found response code.&#x20;
{% endhint %}

### Map Characteristics

The table below summarizes this map's key characteristics:&#x20;

| **Map Characteristics** |                                                                                                        |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| **Spatial resolution**  | 20 meters                                                                                              |
| **Update time**         | Daily at 3AM CET                                                                                       |
| **Tile zoom levels**    | 13 zoom levels                                                                                         |
| **Tile size**           | 256x256 pixels                                                                                         |
| **Default coloring**    | <p>From light blue (#35e9e6) to bright pink (#ff01fb)</p><p>The coloring spreads from 1cm to 2.5m+</p> |
| **Covered area**        | Alpine Convention                                                                                      |

### Map Endpoint

To display the DeFROST European Alps snow cover map as a layer over the base map of your choice, use the URL string below as the Tile Server endpoint:

```http
https://maps.defrost.io/{z}/{x}/{y}.png
```

Pay attention to the fact that as any DeFROST endpoint, JWT Authentication is required for the Tile Server. This means **a valid JWT token has to be set in the HTTP Authorization request header**. Read more about Maps Authentication in the [Maps Overview section](https://docs.defrost.io/defrost-maps/maps-overview#maps-authentication-json-web-tokens).&#x20;


# Global Map

Daily updated snow depth map at 375 meters resolution

DeFROST operates and serves a **daily snow depth map** with 375 meters resolution for the entire world, excluding extreme latitudes (i.e. the arctic and antarctic circles).

![Global Map showing the snow depth and extent in west USA on 20th December 2019](https://1127025084-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Lili0IfPABv5Bgn32Kc%2F-LwY0J_p2dGjo-0NUAFa%2F-LwY7TCvNBfdGTUUDDKL%2FwestUSAdepth20.12.19.png?alt=media\&token=ab9a9598-6452-4b57-9b27-9af9e45697e5)

Polar latitudes are mapped, but are subject to very low resolution and update frequency to seasonal perpetual darkness conditions in winter. Therefore, we currently do not recommend using the global map for latitudes above or below the 66.5° parallels south or north.&#x20;

![Global snow map from 27th November 2019 - red lines indicate latitude coverage boundaries](https://1127025084-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Lili0IfPABv5Bgn32Kc%2F-Lug4reMwb18_cARJnD-%2F-Lug5H9JHRAUNbue4hJY%2Fglobal.png?alt=media\&token=816624bd-7b5e-42d0-a630-fe814c18a92a)

### Map Characteristics

The table below summarizes this map's key characteristics:&#x20;

| **Map Characteristics** |                                                                                                        |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| **Spatial resolution**  | 375 meters                                                                                             |
| **Update time**         | Daily at 4PM CET                                                                                       |
| **Tile zoom levels**    | 9 zoom levels                                                                                          |
| **Tile size**           | 256x256 pixels                                                                                         |
| **Default coloring**    | <p>From light blue (#35e9e6) to bright pink (#ff01fb)</p><p>The coloring spreads from 1cm to 2.5m+</p> |
| **Covered area**        | 66.5°N to 66.5°S                                                                                       |

To illustrate varying snow depths in the global map, the following coloring schema is applied:

![Global Map coloring schema based on snow depth in centimeters](https://1127025084-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Lili0IfPABv5Bgn32Kc%2F-LwY0J_p2dGjo-0NUAFa%2F-LwY6OGG7CV730HrZDie%2Fdepth-scale.png?alt=media\&token=dca2c71f-fe78-44fb-9020-9effa4838b8a)

### Map Endpoint

To display the DeFROST Global snow depth map as a layer over the basemap of your choice, use the URL string below as the Tile Server endpoint:

```http
https://maps.defrost.io/global/v1/{z}/{x}/{y}.png
```

Pay attention to the fact that as any DeFROST endpoint, JWT Authentication is required for the Tile Server. This means **a valid JWT token has to be set in the HTTP Authorization request header**. Read more about Maps Authentication in the [Maps Overview section](https://docs.defrost.io/defrost-maps/maps-overview#maps-authentication-json-web-tokens).&#x20;


# Changelog

Be sure to not miss out on new features and improvements! 🚀

## Coming soon

* :dart: **High resolution snow tiles for custom** areas of interest upon demand.

## v1.4 - 13 Feb 2020

### New Features

* :map:**\[Map] Snow Depth color legend available:** developers have an image and a JSON definition so that their users can interpret the snow depth displayed on the map . Check[ the documentation](https://docs.defrost.io/defrost-maps/maps-overview#map-legend) to learn more about it.

### Changes

* :map:**\[Map] The Alpine Map is now colored to represent snow depth:** the [alpine map endpoint URL](https://docs.defrost.io/defrost-maps/european-alps-map#map-endpoint) now returns a map layer that shows the snow depth in the Alps in different shades from light blue to bright purple.

### Improvements

* :map:**\[Map] The Global Map looks have improved:** the [global tiled map endpoint URL](https://docs.defrost.io/defrost-maps/global-map#map-endpoint) now returns a map layer with smoother edges in areas where snow data is scarcer.

## v1.3 - 19 Dec 2019

### New Features

* :map:**\[Map] Global Snow Depth map available:** we are really excited to release a daily, global-coverage snow depth map! Check [the documentation](https://docs.defrost.io/defrost-maps/global-map) to learn more about it.

### Changes

* :map: the [global tiled map endpoint URL](https://docs.defrost.io/defrost-maps/global-map#map-endpoint) now returns a map layer which shows the snow depth globally in different shades from light blue to bright purple.
* :map:**\[Map] Smooth snow-covered area edges:** the [global map](https://docs.defrost.io/defrost-maps/global-map) has now a neater look & feel thanks to an improved data post-processing which softens the snowy area edges.
* :atom: **\[API] The Snow depth metric has now global coverage:** for any point between latitudes 66.5° north and 66.5° south, the [snow cover API endpoints](https://defrost.io/api-docs#tag/Snow-cover) are now able to include the actual snow depth at that point.

### Improvements

* :atom: **\[API] Snow cover over line API endpoint loads 20x faster:** thanks to this speed improvement, you can compute [snow metrics over any trail or path](https://defrost.io/api-docs#operation/Snow%20cover%20over%20line) and get a response 20 times faster than before while getting the same precision level.

## v1.2.3 - 22 Nov 2019

### Improvements

* :map:**\[Map] Tiles load 41% faster:** we have deployed a few fixes in our servers to be able to manage more map tile requests in parallel, so that we can serve maps 41% faster, in average, than before.
* :atom: **\[API] Snow depth resolution improved**: for the Swiss Alps, you now get snow depth estimations that are closer to the real world's depth thanks to improved resolution in our models.

## v1.2.2 - 15 Nov 2019

### New Features

* :map:**\[Map] Google Maps support:** you can now integrate the DeFROST Maps directly with Google Maps JavaScript API V3! Check [the documentation](https://docs.defrost.io/introduction/development-quickstart#google-maps-users-whitelist-your-http-referrers) and [code examples](https://github.com/wegaw/defrost-examples/blob/master/tests/map_tests/google-map.html) to get started.

## v1.2.1 - 11 Nov 2019

### New Features

* :globe\_with\_meridians: **\[General] Public demo page available:** you can now navigate the latest global snow cover map on our [new demo page](https://defrost.io/demo) and leave your feedback!&#x20;

### Improvements

* :map: **\[Map] Improved snow detection in extremely cloudy regions** while keeping the best resolution available for the [European Alps Map](https://docs.defrost.io/defrost-maps/european-alps-map). This improvement will soon be deployed for the global map.

### Bugfix

* :atom: **\[API] Snow depth endpoint fixed**: After the global map inclusion in version 1.2, the snow depth endpoint started malfunctioning and reporting 0cm anywhere. This bug has been fixed in version 1.2.1. Thanks to our pilot users for reporting.

## v1.2 - 1 Nov 2019

### New Features

* :map: **\[Map]** [**DeFROST Global Snow Cover Map**](https://docs.defrost.io/defrost-maps/global-map) **at 375 meters resolution:** [new Map endpoint](https://docs.defrost.io/defrost-maps/global-map#map-endpoint) offering a fresh daily map on snow coverage between the 70°N and 70°S parallels.&#x20;
* :atom: **\[API] DeFROST Global Snow Cover at 375 meters resolution:** now allows for Snow cover at point and over-line queries anywhere between the 70°N and 70°S parallels.&#x20;

### Changes

* :bangbang: :globe\_with\_meridians: **\[General] DeFROST domain migrates from .ch to .io** : DeFROST is now served, in addition to the previous .ch domain, [under a new .io domain](https://defrost.io). This includes both the website, documentation, API and Maps. The next major version, 2.0 scheduled for first half 2020, will deprecate and discontinue the .ch domain.&#x20;

### Improvements

* :blue\_book: **\[Documentation]** **New DeFROST Maps section**: this section presents and describes the characteristics of both maps operated by DeFROST, this is, the European Alps Map and the Global Map. In addition, it will help you out in setting up your snow cover map! Read more at [Maps Overview](https://docs.defrost.io/defrost-maps/maps-overview).

## v1.1.1 - 16 Oct 2019

### New Features

* :atom: **\[API] The "Snow cover over a line" endpoint returns 2 new metrics**: the minimum and maximum snow depth observed across the points that compose the line you are querying snow for are now returned by the [Snow cover over line](https://defrost.io/api-docs#operation/Snow%20cover%20over%20line) API endpoint.

## v1.1 - 11 Oct 2019

### New Features

* :atom: **\[API] New API Endpoint Snow cover over line**: a new endpoint called[ Snow cover over line](https://defrost.io/api-docs#operation/Snow%20cover%20over%20line) allows you passing a [GeoJSON formatted LineString geometry](https://en.wikipedia.org/wiki/GeoJSON#Geometries) to retrieve the snow cover status for each of the line's point. In addition, this endpoint will return the percentage of the terrain under such line that is covered under snow - by resampling the line to 20 meters.&#x20;

### Changes

* :atom: **\[API] Snow depth is now returned as part of Snow cover at point and over-line endpoints**. A single, interpolated value is returned for each point. For now, we are able to provide snow depth values for locations in the Swiss Alps.&#x20;
* :bangbang: :atom: **\[API] Snow depth endpoint deprecated**: The *Snow depth at point* endpoint is deprecated and will be removed in the next minor version 1.2. The snow depth metric is now returned at the *Snow cover at point* and *Snow cover over line* endpoints, please switch to using those instead.&#x20;

### Improvements

* :cloud: **\[Data]** **Snow cover detection during cloudy periods**: the map will now use the best data available either at 20 or 500 meters resolution to map the snow cover during periods of consistent cloudy conditions over any region. This means that for areas under such conditions, resolution might start dropping down up to 500m while still managing to detect snow. Therefore the perceived "pixel size" on the snow cover map may appear to increase. [Improved in version 1.2.1](https://docs.defrost.io/product-roadmap/changelog#v-1-2-1-11-nov-2019).

## v1.0 - 25 Sept 2019

**DeFROST 1.0 codename ALPINE20 first release!** This is basically including, with coverage for all the European Alpine region (as per the area defined by the Alpine Convention):

* :atom: **DeFROST API**: an endpoint for querying snow cover at any point in the alps. Another endpoint for querying the snow depth for any point.
* :map: **DeFROST Maps**: a TMS standard web map tile server secured by JWT tokens providing DeFROST snow cover map compatible with any major web mapping library such as OpenLayers, Leaflet or Mapbox.


# Maintenance Schedule

We build and ship fast - in an structured way. Find our maintenance timetable below.

In order to offer you the best service we need some housekeeping every now and again. In order not to impact you nor your users, please find our schedule below:

{% hint style="success" %}
**During maintenance windows, DeFROST remains functional**. Minor system interruptions are possible, with less than 60 seconds duration, provoking 502 server response codes to your requests. **99% or above uptime rate is guaranteed** in all cases.
{% endhint %}

### Regular maintenance window <a href="#regular-maintenance" id="regular-maintenance"></a>

**Wednesdays** between **12pm** and **1:30pm** CET.

### Hotfixing window

**Daily** between **12pm** and **12:30pm** CET.

### One-timers&#x20;

Here you can find specific, one-time maintenance windows that we announce in advance, for exceptional cases which require quick incident resolution:

* Tuesday,  26/November/2019 --  **12pm** to **1:45pm** CET


# Sources & References

Backed by a wide range of satellite & weather data, as well as powerful open source code

### Data Sources

Earth Observation satellite and Weather Model data is used to daily produce the underlying global snow dataset that powers both DeFROST Maps and API services. These sources include:

{% tabs %}
{% tab title="Satellite Data" %}

* [Sentinel-2](https://sentinel.esa.int/web/sentinel/missions/sentinel-2), operated by the European Space Agency.
* [VIIRS](https://earthdata.nasa.gov/earth-observation-data/near-real-time/download-nrt-data/viirs-nrt) onboard Suomi-NPP, operated by NASA.
* [MODIS](https://lance-modis.eosdis.nasa.gov/data/modis.php) onboard Terra & Aqua, operated by NASA.
  {% endtab %}

{% tab title="Weather Models" %}

* [ICON-EU](https://www.dwd.de/EN/ourservices/nwp_forecast_data/nwp_forecast_data.html), by Deutscher Wetterdienst.
* [HRDPS](https://weather.gc.ca/grib/grib2_HRDPS_HR_e.html), by Government of Canada.
* [GFS](http://en.wikipedia.org/wiki/Global_Forecast_System), by the National Oceanographic and Atmospheric Administration (USA).
  {% endtab %}

{% tab title="Snow Models" %}

* [SNODAS](https://nsidc.org/data/g02158), by the National Snow and Ice Data Center (USA).
  {% endtab %}
  {% endtabs %}

### Open Source Works

This section highlights some of the Open Source projects that make DeFROST possible and that we actively support.&#x20;

{% hint style="info" %}
**Special mention** goes to the [**Let-It-Snow**](https://gitlab.orfeo-toolbox.org/remote_modules/let-it-snow) module by [CESBIO](https://www.cesbio.cnrs.fr/en/homepage/). DeFROST works with its [custom extension](https://github.com/wegaw/s2-lis-snowcover) of this module for the processing of Sentinel-2 scenes to detect snow on them.

Thanks to Gascoin, S., Grizonnet, M., Bouchet, M., Salgues, G., and Hagolle, O. and all LIS contributors.
{% endhint %}

The list is not exhaustive:

* [Rasterio](https://rasterio.readthedocs.io/en/latest/)
* [Shapely](https://shapely.readthedocs.io/en/latest/manual.html)
* [GeoPandas](https://geopandas.org/)
* [GDAL](https://gdal.org/)
* [QGIS](https://www.qgis.org/en/site/)


