---
## Lesson Objectives
*After this lesson, you will be able to…*
- Describe what an application programming interface (API) is and why we might use one.
- Identify common APIs on the web.
- Call an API.
---
## Discussion: Web Magic
Have you seen…
- A website with Google Maps on the page (like Yelp)?
- A program that had live stock market info?
- A website that isn't Twitter but shows a live Twitter feed?
- Any app that pulls info from somewhere else?
How did they do this?
---
## APIs (Application Program Interfaces)
An API is a service that provides raw data for public use.
APIs give us data, maps, anything!
| What's the API? | Sample URL — put this in a new tab! |
|------|------------|
| **The Star Wars API: Request R2-D2 info** | http://swapi.co/api/people/3 |
| **Markit Digital's API: Request current Apple stock info** | http://dev.markitondemand.com/Api/Quote/xml?symbol=AAPL |
| **OpenWeatherMap: The current weather in London** | https://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=b6907d289e10d714a6e88b30761fae22 |
Do you think you've been on websites that call an API?
> Does the JSON look unreadable in the browser? If you're using Chrome, install the [JSONView plugin](https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc?hl=en).
---
## How Do We Use an API?
We'll use the `requests` module.
```python
import requests
# Call the API by opening the URL and reading the data.
# We use the `get()` function in `requests`.
response = requests.get("")
print(response)
# Prints out the requested information!
```
This works, but there's one very helpful line missing!
Before we see this in action, let's look at what the API might return.
---
## JSON vs. XML
Imagine: You write code for a list.
```python
my_list = [1, 4, 2]
my_list.append(len(my_list))
my_list[1] = "new element!"
for item in my_list:
print item
```
But then, `my_list` is unexpectedly a dictionary, or an int, or even a class! The code we wrote won't work.
APIs can give data back in two ways: JSON or XML. Depending on what the API does, we need to write our program a different way.
---
## How Do APIs Give Us Info? Option 1: JSON
Here's a potential return from an API:
```json
{
"users": [
{"name": "Wonder Woman", "id": 0},
{"name": "Black Panther", "id": 1},
{"name": "Batgirl", "id": 2}
]
}
```
Looks like a dictionary with a list of dictionaries inside it, right?
But it's not a dictionary! It's **JSON** (JavaScript Object Notation).
The `requests` module has a [built-in JSON decoder](http://docs.python-requests.org/en/master/user/quickstart/#json-response-content) to turn JSON into a Python dictionary.
We can **decode** JSON with `decoded_data = response_from_request.json()`.
---
## How Do APIs Give Us Info? Option 2: XML
Instead of JSON, we might get XML:
```html
Wonder WomanBlack PantherBatgirl
```
JSON is certainly easier to read!
- We'll stick with JSON whenever we can.
> **Pro tip:** Most of you don't need to know about XML, but if you're working with legacy code or an older API, you may have to use it. In that case, look up [Element Tree XML](https://python.readthedocs.io/en/stable/library/xml.etree.elementtree.html).
---
## Let's Choose an API
**To recap:** APIs give us data we can use in either XML or JSON.
Let's call one!
Check out http://api.open-notify.org/astros.json, which tells us the people currently aboard the International Space Station (ISS).
```json
{
"number": 5,
"people": [
{"craft": "ISS", "name": "Oleg Novitskiy"},
{"craft": "ISS", "name": "Thomas Pesquet"},
{"craft": "ISS", "name": "Peggy Whitson"},
{"craft": "ISS", "name": "Fyodor Yurchikhin"},
{"craft": "ISS", "name": "Jack Fischer"}
],
"message": "success"
}
```
---
## Calling an API
- Import the `request` module.
- Call the API (`requests.get()`).
- Parse the response with `response.json()`.
---
## You Do: Calling an API
Open a new file, `my_api.py`. Type and run the code:
```python
import requests
# Call the API by opening the URL and reading the data.
response = requests.get("http://api.open-notify.org/astros.json")
# Decode the raw JSON data.
response_data = response.json()
print(response_data)
```
---
## We Do: A New API
Awesome! Go back to your file. Let's instead call this URL:
`http://dev.markitondemand.com/Api/Quote/xml?symbol=AAPL`
Why does it break? We can't parse XML like JSON.
```xml
SUCCESSApple IncAAPL185.51.340.7276281494Thu Jun 28 00:00:00 UTC-04:00 201891175809900017365235169.239.6141346097186.21183.8184.1
```
---
## Quick Review
We've called an API! Great job. We did this with the `get()` function in the `requests` module. APIs are made available by other websites or applications. They give us data we can use in either XML or JSON.
```python
import requests
response = requests.get("http://api.open-notify.org/astros.json")
response_data = response.json()
print(response_data)
```
JSON:
```json
{
"users": [
{"name": "Wonder Woman", "id": 0},
{"name": "Black Panther", "id": 1}
]
}
```
---
## Quick Review
XML:
```html
Wonder WomanBlack Panther
```
---
## You Do: Back to JSON
Back in your file, change the API call back to `http://api.open-notify.org/astros.json`.
Once it's decoded, it's a dictionary!
Replace your `print` statement:
```python
for key, ratings in response_data_decoded.items():
print("Key:", key, "Value:", ratings, "\n")
```
Can we go further? Try to only print the `name`s of the astronauts.
---
## Name Printing: Solution
Working backward, we have a:
- Dictionary (key: `name`).
- Which is inside a list (the value of `people`).
- Which is inside a dictionary (key: `people`).
```
For message the value is success.
For people the value is [{'craft': 'ISS', 'name': 'Oleg Artemyev'}, {'craft': 'ISS', 'name': 'Andrew Feustel'}, .....].
For number the value is 6.
```
```python
for item in response_data_decoded["people"]:
print(item["name"])
```
---
## You Do: Shakespeare
In your file, call the Shakespeare API `http://ShakeItSpeare.com/api/poem`.
Print only the poem.
---
## Shakespeare: Solution
Print only the poem.
```python
import requests
# Call the API by opening the URL and reading the data.
response = requests.get("http://ShakeItSpeare.com/api/poem")
# Decode the raw JSON data.
response_data = response.json()
print(response_data["poem"])
```
---
## Quick Review
When we convert JSON, it keeps the same format, only in a Python structure.
When parsing an API's return, look through the JSON to find the exact structure you need. Is it the string value from the `poem` key? Or the value from each `name` key in a list of dictionaries, which is the value of the `people` key?
Think it through before writing your code.
```python
# From the ISS API:
{ # The outer dictionary
"number": 5, # Key: value
"people": [ # Key and value, again. Here, the value is a list of dictionaries.
{"craft": "ISS", "name": "Oleg Novitskiy"},
{"craft": "ISS", "name": "Thomas Pesquet"},
{"craft": "ISS", "name": "Peggy Whitson"},
{"craft": "ISS", "name": "Fyodor Yurchikhin"},
{"craft": "ISS", "name": "Jack Fischer"}
],
"message": "success" # Key and value.
}
# From the Shakespeare API
{ # The outer dictionary.
# The first key: value is the poem.
'poem': 'Pardoned!\nNurs.\nBepaint my cheek?',
'markov': 2, # The second key: value pair.
'lines': 3 # The third key: value pair. This is the number of lines in the poem.
}
```
---
## I Do: API Authentication
Many APIs are free but require a **key**. This identifies the developer requesting access.
If we call the Giphy API:
- With no key, `http://api.giphy.com/v1/gifs/search?q=funny+cat`, we get `Error - Unauthorized`!
- With a key, `http://api.giphy.com/v1/gifs/search?q=funny+cat&api_key=dc6zaTOxFJmzC`, it works!
---
## I Do: API Authentication
Syntax Notes:
- The main API URL is `http://api.giphy.com/v1/gifs/search`.
- `?` always delineates a URL and its parameters.
- (The `?` is a standard for every URL! Searching Google for "banana," with `q` short for "query:" `https://www.google.com/search?q=banana`).
- (Here's another one! Searching Amazon for "banana:" `https://www.amazon.com/s?field-keywords=banana`.)
**Most importantly**, never publish your key for a backend service, including on GitHub! (This is an example.) There are other ways to provide your key to a server in order to keep that key safe. However, if your code is using JavaScript, that's ok as that provides only read access in general (assuming you have your permissions properly configured.) This is a sticking point for developers coming to Python from a front-end perspective.
---
## You Do: JSONPlaceholder API
Read about the API here.
Call this URL: https://jsonplaceholder.typicode.com/users/1 .
- Display the name, username, email and phone that came back from the API.
---
## JSONPlaceholder API Solution
---
## Summary
APIs:
- Handy URLs from which we can get information.
- Sometimes require keys.
- Usually free.
- Call with the `requests()` module.
XML and JSON:
- Two formats in which APIs might return information to us.
- XML is legacy.
- JSON looks like a dictionary.
---
## Additional Resources
- Here's an example of a [stolen key horror story](https://wptavern.com/ryan-hellyers-aws-nightmare-leaked-access-keys-result-in-a-6000-bill-overnight).
- The [Programmable Web API Directory](http://www.programmableweb.com/apis/directory)
- [Element Tree XML](https://python.readthedocs.io/en/stable/library/xml.etree.elementtree.html)