{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 001. Data download using cdsapi\n",
    "\n",
    "The Copernicus Climate Change Service API (https://cds.climate.copernicus.eu/) is a platform for the distribution of observations of the earth system funded by the European Union. All downloads are for free.\n",
    "\n",
    "We downloaded ERA5 data for a spatial subset. The description and metadata can be found here:\n",
    "https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels?tab=overview\n",
    "\n",
    "Lately, the discharge datasets were published too. You can find the historical, i.e. reanalysis dataset here: https://cds.climate.copernicus.eu/cdsapp#!/dataset/efas-historical?tab=overview. The current forecast runs since 2018 are available here: https://cds.climate.copernicus.eu/cdsapp#!/dataset/efas-forecast?tab=overview.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## API documentation: \n",
    "There is a python API that allows you to download the datasets in a systematic manner. The code is hosted at https://pypi.org/project/cdsapi/. \n",
    "\n",
    "### 1) Install with pip"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Requirement already satisfied: cdsapi in /home/opt/anaconda3/lib/python3.7/site-packages (0.1.4)\n",
      "Requirement already satisfied: requests>=2.5.0 in /home/opt/anaconda3/lib/python3.7/site-packages (from cdsapi) (2.21.0)\n",
      "Requirement already satisfied: certifi>=2017.4.17 in /home/opt/anaconda3/lib/python3.7/site-packages (from requests>=2.5.0->cdsapi) (2019.3.9)\n",
      "Requirement already satisfied: chardet<3.1.0,>=3.0.2 in /home/opt/anaconda3/lib/python3.7/site-packages (from requests>=2.5.0->cdsapi) (3.0.4)\n",
      "Requirement already satisfied: urllib3<1.25,>=1.21.1 in /home/opt/anaconda3/lib/python3.7/site-packages (from requests>=2.5.0->cdsapi) (1.24.2)\n",
      "Requirement already satisfied: idna<2.9,>=2.5 in /home/opt/anaconda3/lib/python3.7/site-packages (from requests>=2.5.0->cdsapi) (2.8)\n",
      "^C\n",
      "\u001b[31mERROR: Operation cancelled by user\u001b[0m\n"
     ]
    }
   ],
   "source": [
    "!pip install cdsapi"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2) Register at https://cds.climate.copernicus.eu/ \n",
    "\n",
    "#### Get your UID and API key from https://cds.climate.copernicus.eu/user and insert it in the variables below"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [],
   "source": [
    "UID = 'UID'\n",
    "API_key = 'API key'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Write the keys into the file  `~/.cdsapirc`  in the home directory of your user"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "with open(os.path.join(os.path.expanduser('~'), '.cdsapirc2'), 'w') as f:\n",
    "    f.write('url: https://cds.climate.copernicus.eu/api/v2\\n')\n",
    "    f.write(f'key: {UID}:{API_key}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3) Start a request \n",
    "You will be asked to agree to the terms of use from the copernicus climate data store for your first download."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "2019-05-22 18:12:33,877 INFO Sending request to https://cds.climate.copernicus.eu/api/v2/resources/reanalysis-era5-pressure-levels\n",
      "2019-05-22 18:12:34,146 INFO Request is queued\n"
     ]
    }
   ],
   "source": [
    "# Import cdsapi and create a Client instance\n",
    "import cdsapi\n",
    "c = cdsapi.Client()\n",
    "# More complex request\n",
    "c.retrieve(\"reanalysis-era5-pressure-levels\", {\n",
    "            \"product_type\":   \"reanalysis\",\n",
    "            \"format\":         \"netcdf\",\n",
    "            \"area\":           \"52.00/2.00/40.00/20.00\", # N/W/S/E\n",
    "            \"variable\":       \"geopotential\",\n",
    "            \"pressure_level\": \"500\",\n",
    "            \"year\":           \"2017\",\n",
    "            \"month\":          \"01\",\n",
    "            \"day\":            \"12\",\n",
    "            \"time\":           \"00\"\n",
    "            }, \"example_era5_geopot_700.nc\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}