Examples/Setting up an API key.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Setting up an API key\n",
    "\n",
    "## Table of Contents\n",
    "1. [Generate API key](#generate-api-key)\n",
    "    1. [Sign up](#sign-up)\n",
    "    2. [Create project](#create-project)\n",
    "    3. [Add API to project](#add-api)\n",
    "2. [Using the api key](#use-api-key)\n",
    "\n",
    "In order to use `osdatahub` you will need to provide it with an API key. This notebook will guide you through the simple process of creating an account in the OS Data Hub, making an API key, and then using that API key with `osdatahub`.\n",
    "\n",
    "## Generate API key  <a name=\"generate-api-key\"></a>\n",
    "\n",
    "`osdatahub` gets its data from a service called \"OS Data Hub\". In order for the python package to get data from the Data Hub you need to have an account with the Data Hub and an API key. Creating an account only takes a few seconds, first navigate to the Data Hub homepage at https://osdatahub.os.uk/\n",
    "\n",
    "### Sign up <a name=\"sign-up\"></a>\n",
    "Once you have navigated to the homepage click \"sign up\" in the top right and then follow the instructions to create an account. There are several options that allow you to get started for free.\n",
    "![Homepage](https://raw.githubusercontent.com/OrdnanceSurvey/osdatahub/master/Examples/images/1_homescreen.PNG \"Homepage\")\n",
    "<!-- ![Sign up](images/2_sign_up.png \"Sign up\") -->\n",
    "\n",
    "---\n",
    "### Create project <a name=\"create-project\"></a>\n",
    "Once you have created an account you need to create a project.\n",
    "\n",
    "A project is a useful way of keeping track of how much data you are using. You could have multiple projects and then monitor the data use of each one. To create a project:\n",
    "- select \"API Dashboard\" in the header\n",
    "- then \"my projects\" in the menu on the left\n",
    "- and then create new project near the top right\n",
    "\n",
    "For this example, we have create a project called \"API wrapper\"\n",
    "\n",
    "![New project](https://raw.githubusercontent.com/OrdnanceSurvey/osdatahub/master/Examples/images/4_new_project.PNG \"New project\")\n",
    "\n",
    "---\n",
    "### Add API to project <a name=\"add-api\"></a>\n",
    "Now that you have a project you can choose what API services you want to add to the project. For example, you might need access to the OS Features API and OS Places API. \n",
    "\n",
    "To add an API to a project:\n",
    "- go to the API Dashbaord\n",
    "- Choose APIs on the left menu\n",
    "- Choose which API you want to add to your project (for this project select the Features API)\n",
    "\n",
    "![Add api](https://raw.githubusercontent.com/OrdnanceSurvey/osdatahub/master/Examples/images/5_add_api_to_project.PNG \"Add api\")\n",
    "\n",
    "---\n",
    "## Using the api key <a name=\"use-api-key\" />\n",
    "After you have added an API to your project will be able to see the API project key in \"My projects\". This key will enable you to access all of the APIs you've added to your project. For example, if you create a project and add the Features and Places API then you don't need a separate key to access both services.\n",
    "\n",
    "The rest of this example will show you how to make a simple query with `osdatahub`. Once you have copied the API we suggest following best practices and storing it as an environment variable - for this tutorial we store the API key as an environment variable called `OS_API_KEY`. Creating an environment variable is beyond the scope of this tutorial but you can find examples of how to do this online.\n",
    "\n",
    "<span style=\"color: red\">You can use `osdatahub` without setting an enviroment variable - this approach is also shown below - but this is discouraged. If you choose to use the paste the API directly into your sode make sure you don't have it publicly accessible.</span>\n",
    "![View api key](https://raw.githubusercontent.com/OrdnanceSurvey/osdatahub/master/Examples/images/6_view_api_key.PNG \"View api key\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "42\n"
     ]
    }
   ],
   "source": [
    "from os import environ\n",
    "\n",
    "from osdatahub import Extent\n",
    "from osdatahub import FeaturesAPI \n",
    "\n",
    "# If you havent set an enviroment variable you can do the following instead. (Not recommended)\n",
    "# key = \"**PROJECT-API-KEY**\"\n",
    "\n",
    "# Get key from enviroment\n",
    "key = environ.get(\"OS_API_KEY\")\n",
    "\n",
    "# Create a bounding box\n",
    "extent = Extent.from_bbox((-3.2939550711619177, 50.746391786819316,\n",
    "                           -3.2788419310229244, 50.75566426785872), \"EPSG:4326\")\n",
    "\n",
    "# Query fetaures from the features api\n",
    "features = FeaturesAPI(key, \"topographic_area\", extent)\n",
    "results = features.query(limit=42)\n",
    "\n",
    "print(len(results[\"features\"]))"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "osdatahub-notebooks",
   "language": "python",
   "name": "osdatahub-notebooks"
  },
  "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.8.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}