Using a REST API in Python and encapsulate with our own with Flask

A REpresentational State Transfer (REST) is an application program interface (API) paradigm that employs HTTP requests to GET, PUT, POST, and DELETE data. With request module in Python, it is super easy to use a REST API to get the data from any web service. In addition, with Flask, it’s easy to deploy our own REST API server. This comes handy when we need to fetch some data from the web via available APIs and need to do a few data manipulation before using it finally. Here, I document the usage of both i.e. using an existing API to get the data and then serving the data in the final form with some postprocessing.

For this demo, I am building an API that finds the nearby public toilets from the given coordinates (and radius, if provided) and then gives their distances from the queried point.

Part 1: Getting the data from the web

For getting the basic data, we could directly use OpenStreetMap (OSM) which has a vast amount of information. Overpass query language (OQL) provides a convenient way to query the data from OSM. There are many great tutorials available to get started with OSM and OQL: OQL official and from mapsaregreat. FindToilets class in request_data_osm.py does the work to find the nearby toilets from OSM with OQL. You can get a nice pandas dataframe by just querying as follow:

find_wc = FindToilets(radius=600,lat=12.973132,lon=77.601479).provide_dataframe()

You can read and change as per your taste. The default radius is 100 m with some default coordinates. The fetch_data_from_overpass function is where we request for the data from OSM. As said, after querying the data from OSM, we calculate the distance (straight-line distance) between the queried point and the toilets and return it along with the data of OSM.

Part 2: Setting up our own REST server with Flask

Flask is a web framework in Python and it is fairly easy to set up a server. Before we jump to the code, let’s have a look at the template folder, which contains the basic HTML code and it can be opened in any internet browser to query from our Flask server (once we start running it) like a web-app (very basic app!). main_api.py file has the code for Flask based API. All functions decorated with @app.route are related to Flask and it provides a routing (like homepage and child pages). Our home page simply shows the predefined template which serves as a web-app (alongside our REST service). Our REST api resides at /api/v1/toilets wrt. the homepage.

Once all dependencies have been installed, we can start the rest API from our terminal by running this script. As we are running it in the Debug mode, so all the logs with a lot of other information will be logged in and will be displayed on the terminal. If the server is started successfully, then we can open our home page: http://localhost:5000/, which will be the web-app for us. Here, we can fill out the coordinates and the radius and by pressing the submit button, we will get the data in JSON (geojson to be more precise). As said, we would like to have a programmatic way to access this data via REST, which would be possible with an address like: http://127.0.0.1:5000/api/v1/toilets?src=12.973132,77.601479&radius=500 It will also give us similar data.