Working with the Google Photos API is not easy especially for me despite being able to develop some codes to automatically download media from Google Photos, as written in here. I was looking at the One Map API documentations and they too would need me to work with REST API. I’ve decided to take the time to learn how to work with REST API. The post by Real Python has been really helpful.

What is API?

API is short for ‘Application Programming Interface’. It is simply a messenger that allows a client, be it you or a third party application, to interact with another server’s resources.

API

Credit goes to g2.com

Above is a simple diagram of how an API work. You are using a web browser to make a search. That search is a request sent via API to Google’s search engine server. Relevant information are extracted and sent back to you, again, via API and is displayed in your web browser.

What is REST API?

REST is short for ‘Representational State Transfer’. It is simply a software architecture style that defines the pattern for client and server communications over a network. The other prominent software architecture is SOAP, which stands for ‘Simple Object Access Protocol’.

REST is meant to address the shortcomings of SOAP API and provide a more user-friendly interface to access resources. Though how REST addresses the shortcomings is entirely unknown to me at the moment.

For more information on API and REST API, you could refer to the references below.

Learning REST API

What’s the best way to learn working with REST API than to actually work with REST API. I’ll be working with the OneMap API. Of course, you could work with the Python wrapper client for the OneMap API (onemapsg) but where’s the fun in that.

For simple introduction, you could refer to this article by Real Python.

OneMap API

To get the necessary data, you’ll need to use two main packages: requests and socket, and of course, pandas for the data manipulation!

The below code is necessary to enforce the API call to be done via IPv4. Else, the API may take longer than expected.

# Force IPv4, run this before any requests
import socket
import requests.packages.urllib3.util.connection as urllib3_cn
 
def allowed_gai_family():
    family = socket.AF_INET    # force IPv4
    return family
 
urllib3_cn.allowed_gai_family = allowed_gai_family

Taking the search API in OneMap as an example, you’ll see that the Usage indicates the API URL, otherwise known as API endpoint. Note that the base URL, https://developers.onemap.sg is omited from the Usage.

Usage:
/commonapi/search?searchVal={SearchText}&returnGeom={Y/N}&getAddrDetails={Y/N}&pageNum={PageNumber}

In the endpoint, you’ll see objects in curly brackets, which are the variables that need to be defined, though not all are mandatory variables. You could read more about it in the documentation.

What I am interested to do is to extract the address details for a particular postal code, in this example, my current employer - National University Health System. The postal code is 119228 and the address is NUHS Tower Block, 1E Kent Ridge Road. Let’s see whether the API returns the same results.

Below is my codes:

SearchText = 119228
returnGeom = "Y"
getAddrDetails = "Y"
api_url = f"https://developers.onemap.sg/commonapi/search?searchVal={SearchText}&returnGeom={returnGeom}&getAddrDetails={getAddrDetails}"
response = requests.get(api_url)
response.json()

And the response is:

{'found': 1,
 'totalNumPages': 1,
 'pageNum': 1,
 'results': [{'SEARCHVAL': 'NATIONAL UNIVERSITY HOSPITAL (NATIONAL UNIVERSITY HLTH SYSTM BLDG)',
   'BLK_NO': '1E',
   'ROAD_NAME': 'KENT RIDGE ROAD',
   'BUILDING': 'NATIONAL UNIVERSITY HOSPITAL (NATIONAL UNIVERSITY HLTH SYSTM BLDG)',
   'ADDRESS': '1E KENT RIDGE ROAD NATIONAL UNIVERSITY HOSPITAL (NATIONAL UNIVERSITY HLTH SYSTM BLDG) SINGAPORE 119228',
   'POSTAL': '119228',
   'X': '22452.3422039868',
   'Y': '30526.9577966947',
   'LATITUDE': '1.29234898139799',
   'LONGITUDE': '103.783470532707',
   'LONGTITUDE': '103.783470532707'}]}

I pretty much got the same address details. Not only that, the search API returns the coordinates of the postal code as well (in terms of X and Y and also latitude and longitude). The coordinates would be valuable when one needs to do a geospatial analysis.

References

https://www.g2.com/articles/what-is-an-api
https://aws.amazon.com/what-is/restful-api/
https://realpython.com/api-integration-in-python/
https://www.onemap.gov.sg/docs/#introduction
https://pypi.org/project/onemapsg/