python-tutorials/tutorials-slide.qmd at main · openaq/python-tutorials · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
---
title: "OpenAQ Python Training"
author: "Minh Nghiem"
format:
    revealjs:
        slide-number: true
        logo: images/openaq-logo.png

include-in-header:
  - text: |
      <style>
      .reveal .slide-logo {
        max-height: unset;
        height: 200px;
      }
      </style>
---

## About the Python SDK
- Part of our core tech products
- Allows you to connect to our API and programmatically access air quality data hosted on OpenAQ platform
- Latest version: **1.0.0rc2**

---

## Why use the Python SDK?
- Accessing air quality data in bulk, from any location and any time
- User-friendly helpers: expressive error handling, preemptive error catching, automatic rate limiting
- More intuitive data access: Python objects-oriented instead of API json responses
- Fully typed: autocomplete, inline documentation

---

## Data models {.smaller}
![](images/data-models.png){width="880px" height="500px"}

For a full definition of each resource, visit our [Python documentation website](https://openaq.github.io/openaq-python/).


## Data models {.smaller}
![](images/data-models-highlight.png){width="880px" height="500px"}

For a full definition of each resource, visit our [Python documentation website](https://openaq.github.io/openaq-python/).


# Key concepts

## API key

The OpenAQ API uses API keys to authenticate requests and manage access.

- control usage and enforce rate limits
- unique and can be requested anew to each users.

::: {.callout-important}
Do not share your API key with anyone.
:::

## Rate limiting {.smaller}
Our API limits users' usage at:

- 60 requests/minute
- 2,000 requests/hour

::: {.callout-note}
From v1.0.0rc1, our Python package supports automatic rate limiting.
:::

::: {.callout-tip}
If a rate limit is exceeded, the API returns a 429 “Too many requests” HTTP status code. Avoid making more requests during this time to prevent further errors.
:::

::: {.callout-warning}
Exceeding API rate limits repeatedly can lead to either a temporary or permanent ban from the OpenAQ API.
:::

## Pagination {.smaller}

- By default, a request will return a maximum of 100 results a page. This is adjustable and can be set up to 1,000 results per page using `limit=1000`.

- If a request returns more than 1,000 results, you can loop through the pages until no more data is found.

::: {.callout-tip}
Querying the entire dataset and paging can be slow. Adding constraints will help your requests be more performative, especially for volume-intensive resources like Measurements.
:::

``` {python}
{
    "meta": {
        "name": "openaq-api",
        "website": "/",
        "page": 1,
        "limit": 1000,
        "found": ">1000"
    }
}
```

# Tutorials

---

## Overview {.smaller}

The tutorial is exercises-driven and works as a primer to OpenAQ Python SDK. Having the code run on your machine as we go is encouraged but entirely optional.

<br>

#### If you want to run the code on your computer as you follow along, make sure you have:

- A [molab account](https://molab.marimo.io)
- Your own [OpenAQ API key](https://explore.openaq.org/register)

## Let's start {.smaller}

**Step 1:** Go to [this link](https://molab.marimo.io/notebooks/nb_ZKWukmCxii1C4ymqq8j8ZV) to create a notebook session for this tutorials

**Step 2:** Once you're in the link:

- Click “Fork and Run” at the top of the page. You will be prompted to log in to your molab account if you’re currently logged out.
- Once you have logged in, you will be automatically redirected to your own forked version of the notebook on the web.
- The notebook is yours to play with and will also be accessible to you via your molab homepage.

---

## Useful links
- [OpenAQ Python SDK documentation](https://openaq.github.io/openaq-python/) (WIP)
- [OpenAQ API documentation](https://docs.openaq.org/)
- [OpenAQ Explorer](https://explore.openaq.org/#1.2/20/40)
- Join [OpenAQ slack channel](https://openaq.slack.com/join/shared_invite/zt-3ga21nbn9-GIFP2NfNTdS0I9OMuKUEbw#/shared-invite/email) for questions and discussions anything air data