Merge pull request #141 from realpython/consuming-apis-python

Materials for Consuming APIs article

Author: jaschmitt

consuming-apis-python/covid.py

@@ -0,0 +1,29 @@
+import requests
+
+# The datetime package is useful to manipulate dates.
+from datetime import date, timedelta
+
+# To fetch the latest total confirmed cases number you need to pass a 24h
+# window to the API. That's why you need to pass both yesterday's date
+# and today's.
+today = date.today()
+yesterday = today - timedelta(days=1)
+
+# Pick a country slug from the list: https://api.covid19api.com/countries
+country = "germany"
+
+endpoint = f"https://api.covid19api.com/country/{country}/status/confirmed"
+params = {"from": str(yesterday), "to": str(today)}
+
+# The response will be a list of results per day, in your case only 1 result.
+response = requests.get(endpoint, params=params).json()
+
+# Finally, you need to traverse through the response and increment the
+# `total_confirmed` variable with the total number of confirmed cases
+# available that day, which is in the field `Cases`.
+total_confirmed = 0
+for day in response:
+    cases = day.get("Cases", 0)
+    total_confirmed += cases
+
+print(f"Total Confirmed Covid-19 cases in {country}: {total_confirmed}")

consuming-apis-python/giphy_search.py

@@ -0,0 +1,24 @@
+import requests
+
+# REPLACE the following with the API key you generated.
+API_KEY = "REPLACE_DEMO_API_KEY"
+
+endpoint = "https://api.giphy.com/v1/gifs/search"
+
+# Define the search term you want to use.
+search_term = "shrug"
+
+# In the query parameters you can define:
+# 1. The number of GIFs to return using the `limit` parameter.
+# 2. The query term to search for using the `q` parameter.
+# 3. The accepted rating of the GIFs returned using the `rating` parameter
+# https://developers.giphy.com/docs/optional-settings#rating
+params = {"api_key": API_KEY, "limit": 3, "q": search_term, "rating": "g"}
+
+# The response will contain a list with all the GIFs that match your query.
+# For each of those, you want to get the `title` and `url` fields.
+response = requests.get(endpoint, params=params).json()
+for gif in response["data"]:
+    title = gif["title"]
+    url = gif["url"]
+    print("%s | %s" % (title, url))

consuming-apis-python/giphy_trending.py

@@ -0,0 +1,22 @@
+import requests
+
+# REPLACE the following with the API key you generated.
+API_KEY = "REPLACE_DEMO_API_KEY"
+
+endpoint = "https://api.giphy.com/v1/gifs/trending"
+
+# In the query parameters you can define:
+# 1. The number of GIFs to return using the `limit` parameter.
+# 2. The accepted rating of the GIFs returned using the `rating` parameter
+# https://developers.giphy.com/docs/optional-settings#rating
+params = {"api_key": API_KEY, "limit": 3, "rating": "g"}
+
+# The response will contain a list with all the GIFs that match your query.
+# For each of those, you want to get the `title`, `url` and the
+# `trending_datetime` fields.
+response = requests.get(endpoint, params=params).json()
+for gif in response["data"]:
+    title = gif["title"]
+    trending_date = gif["trending_datetime"]
+    url = gif["url"]
+    print("%s | %s | %s" % (title, trending_date, url))

consuming-apis-python/github.py

@@ -0,0 +1,100 @@
+import requests
+
+# First, make sure to follow the steps to create your own GitHub application:
+# https://docs.github.com/en/free-pro-team@latest/developers/apps/creating-an-oauth-app
+
+
+# REPLACE the following variables with your Client ID and Client Secret
+CLIENT_ID = "<REPLACE_WITH_CLIENT_ID>"
+CLIENT_SECRET = "<REPLACE_WITH_CLIENT_SECRET>"
+
+# REPLACE the following variable with what you added in the
+# "Authorization callback URL" field.
+REDIRECT_URI = "<REPLACE_WITH_REDIRECT_URI>"
+
+
+# In this method you'll ask the GitHub API for a URL to redirect the user
+# for authentication.
+def create_oauth_link():
+    params = {
+        "client_id": CLIENT_ID,
+        "redirect_uri": REDIRECT_URI,
+        "scope": "user",
+        "response_type": "code",
+    }
+
+    # This endpoint is defined in the GitHub documentation:
+    # https://docs.github.com/en/free-pro-team@latest/developers/apps/authorizing-oauth-apps#1-request-a-users-github-identity
+    endpoint = "https://github.com/login/oauth/authorize"
+
+    response = requests.get(endpoint, params=params)
+
+    # When you make the request above, GitHub will redirect you to their
+    # website to input your credentials. Since you're doing this
+    # programmatically, you need to get the `url` parameter and print it in
+    # the console instead.
+    url = response.url
+
+    return url
+
+
+# In this method you'll exchange the code you got from the GitHub API with
+# an access token.
+def exchange_code_for_access_token(code=None):
+    params = {
+        "client_id": CLIENT_ID,
+        "client_secret": CLIENT_SECRET,
+        "redirect_uri": REDIRECT_URI,
+        "code": code,
+    }
+
+    # Here you define the content type you're expecting to get.
+    # In this case – JSON.
+    headers = {"Accept": "application/json"}
+
+    # This endpoint is defined in the GitHub documentation:
+    # https://docs.github.com/en/free-pro-team@latest/developers/apps/authorizing-oauth-apps#2-users-are-redirected-back-to-your-site-by-github
+    endpoint = "https://github.com/login/oauth/access_token"
+
+    response = requests.post(endpoint, params=params, headers=headers).json()
+    return response["access_token"]
+
+
+# Finally in this method you'll print the user information re. its name,
+# username and number of private repositories.
+def print_user_info(access_token=None):
+    # Now you need to send the `access_token` in the headers
+    # when calling the API.
+    headers = {"Authorization": f"token {access_token}"}
+
+    # This endpoint is defined in the GitHub documentation:
+    # https://docs.github.com/en/free-pro-team@latest/rest/reference/users#get-the-authenticated-user
+    endpoint = "https://api.github.com/user"
+
+    response = requests.get(endpoint, headers=headers).json()
+
+    # The response will be a dictionary with multiple user-related field.
+    # You can try `print(response)` to see all of them.
+    name = response["name"]
+    username = response["login"]
+    private_repos_count = response["total_private_repos"]
+    print(
+        f"{name} ({username}) | "
+        f"number of private repositories: {private_repos_count}"
+    )
+
+
+# So, one last time, step by step:
+# 1. Create a link to redirect the user to for authentication:
+link = create_oauth_link()
+print(f"Follow the link to start the authentication with GitHub: {link}")
+
+# 2. Paste the code you got from GitHub after authenticating
+code = input("GitHub code: ")
+
+# 3. Exchange that code with an access token
+access_token = exchange_code_for_access_token(code)
+print(f"Exchanged code {code} with access token: {access_token}")
+
+# 4. Fetch user information
+print_user_info(access_token=access_token)

consuming-apis-python/google_books.py

@@ -0,0 +1,26 @@
+import requests
+
+endpoint = "https://www.googleapis.com/books/v1/volumes"
+
+# Define the search term you want to use.
+query = "moby dick"
+
+# In the query parameters you can define:
+# 1. The number of books to return using the `maxResults` parameter.
+# 2. The query term to search for using the `q` parameter.
+params = {"q": query, "maxResults": 3}
+
+# The response will contain a list of books that match your query.
+response = requests.get(endpoint, params=params).json()
+for book in response["items"]:
+    # In order to fetch the title, published date and description,
+    # you first need to fetch the volume.
+    volume = book["volumeInfo"]
+
+    # You can fetch these and other attributes from the book using
+    # the specific volume
+    title = volume["title"]
+    published = volume["publishedDate"]
+    description = volume["description"]
+
+    print("%s (%s) | %s" % (title, published, description))