README.md

API Wizardry

A Crash Course in Using Web APIs

Be sure to also check out the slides from the workshop.

Quick Start Brick Stacking

To start the Quick Start notebook, first click this button: and then click on the quick-trick-brick-stack.ipynb notebook file to start it.

The Jupyter notebook has code cells and documentation cells. When you first open a Jupyter notebook, none of the code has been run (though you may see the saved output from previous runs). Click on a cell to select it. Use shift-return to execute the code or just the return key to edit the code. You can also run all the code cells by choosing "Run all" under the "Cells" menu.

Here's a cheat sheet for using Jupyter notebooks, and here's a brief tutorial.

Also you may be interested in keyboard shortcuts for Jupyter notebooks.

Cat API

This is a simple example to demonstrate how requests works and how to make GET requests.

To start this notebook, first click this button: and then click on the cat_api.ipynb notebook file to start it.

Pizza API

In this notebook, you will use an API to:

• Find the nearest Domino's Pizza.
• Explore its menu
• Send an order to that store.
• Track the order as it's delivered to you.

To start this notebook, first click this button: and then click on the pizza.ipynb notebook file to start it.

Thanks to RIAEvangelist for compiling all of this information into a node tool for ordering pizza.

Pizza tracker

This short notebook, is a slightly modified copy of the last few cells of the Pizza API notebook. In it, you can run a loop that will check the status of a pizza order every 3 seconds.

To start this notebook, first click this button: and then click on the pizza-tracker.ipynb notebook file to start it.

Port Authority TrueTime API

In this notebook, you will:

• Look up a bus stop
• Get predicted arrival times for the next bus coming to that bus stop
• Display the bus and the bus stop on a web map

To start the Port Authority TrueTime notebook, first click this button: and then click on the port-authority-examples.ipynb notebook file to start it.

This API requires an API key which you can get on their TrueTime website. You will need to create an account and request an API key from them. Once you have an account, you can log in and browse the documentation.

We use a local settings file in this example to protect our secret API key. See Using your own settings file, to see how to make your own. Or you can simply supply your own API key in the code per the instructions in the notebook.

TwitterBot Demo

This notebook collects crime data from the WPRDC and tweets a message about it.

To start the TwitterBot notebook, first click this button: and then click on the twitter_bot_demo.ipynb notebook file to start it.

The Twitter API requires API keys. Please follow their documentation to find out how to get some.

Feel free to tweet all your results and API outputs to a special account we set up for this event: codeforpizza

Other Things to Try

Click this button to access all our sample notebooks:

Ideas Using WPRDC Datasets

• Right-of-way Permits ⇒ Post notification of road closures delivered to Reddit

• Arrests/Non-traffic citations/Police blotter (updates daily) ⇒ Daily crime report for your neighborhood by Twitter

• Fire incidents (updates daily) ⇒ Notification of all of yesterday's five-alarm fires in Pittsburgh

• BigBurgh Social Services Listings (updates monthly) ⇒ Post local social services and relevant events to Reddit

• 311 Data (updates every 10 minutes) ⇒ Look for spikes in Snow/Ice removal requests and send yourself dangerous-road-conditions text messages

• 311 Data (updates every 10 minutes) ⇒ Generate Spotify list inspired by recent 311 complaints

• Library locations + hours of operation ⇒ Send complementary pizzas to a random library location if it's open.

• City-Wide Revenues and Expenses ⇒ Build a budget ticker that shows how much the city of Pittsburgh government spent each day.

• Restaurant Roulette ⇒ Randomly choose a restaurant for the user to go to, based on their location and aversion to food-safety violations.

• Factoid factory: Combine facts culled from different WPRDC datasets and post a new one to Twitter every day or every hour or at random intervals.

Tools

• JSON viewer extension for Chrome
• Postman - graphical interface for exploring APIs
• curl - command line interface for making HTTP requests
• requests - python library making HTTP requests
• fetch - JS methods for making HTTP requests

Popular Web APIs

• CKAN API documentation
  • WPRDC CKAN instance (where you can get lots of open data)
  • Python wrapper for CKAN API
  • R wrapper for CKAN API
• Port Authority TrueTime - you need to make an account to see documentation
• Spotify API homepage
  • Documentation
  • API Console
• Twilio API Documentation
• Reddit API Documentation - they haven't updated with their design changes, but it should still work
  • r/redditdev - subreddit for people using reddit API
• Twitter API Documentation
• World Cup API - made by someone on HackerNews

Online Resources

• WPRDC
• Mozilla's HTTP overview
• OAuth 2.0 Docs
• REST Wikipedia article - a special class of web APIs

Using Your Own Settings File

For several notebooks, we use a local settings file called settings.py to hide our secret information during demonstartions. You can easily make your own by renmaing settings-example.py to settings.py and changing our fake values to your real values.

In a Jupyter notebook, you can rename it by selecting the checkbox to the left of settings-example.py and clicking the Rename button in the toolbar. You can then enter your own information into that file and you'll be good to go!

In macOS and linux terminals, you can use the command below, or simple rename it like you would any other file.

mv settings-example.py settings.py

The settings file is full of comments explaining what each variable is and how to go about changing it.