This article was written by Nelson Chiu, ERS
Data sharing commonly occurs by sending files over shared drives or email or providing direct access to a database. APIs (which stand for application programming interfaces) are becoming the best practice of making data more accessible for developers and third parties. Google Maps, for instance, created an API that allows third-party developers to embed maps into their product or complement other companies that are location-based like Yelp and Twitter. This improves Google Map’s brand recognition while also providing revenue streams from their users. Smaller companies can create APIs to provide data to a client via a dashboard or to allow access to data across internal teams. In an engineering setting, available APIs that are used every day include NOAA for retrieval of historical weather data and NREL PVWatts to retrieve solar generation outputs.
The most common type of API uses HTTP (Hypertext Transfer Protocol) as its data transfer protocol. This is the same protocol we use every day to request data from web servers, which then render the data into webpages where we view our news and emails. An HTTP works by sending a request to a server and receiving a response. A HTTP API request is comprised of a Method, API URL + Endpoint, Header, and Body. Below is a list of typical values for each component:
- Method: Choose GET, POST, PUT, or DELETE
- GET → Read existing data
- POST → Creates new data
- PUT → Update and replace existing data
- DELETE → Delete existing data
- API URL+ Endpoint: Where to send the request to?
- In our example, we’ll send it to Google Maps: https://maps.googleapis.com/maps/api/endpoint?parameters
- Header: Insert details for content-type and authorization
- Content-Type: application/json
Authorization: Bearer Access-Token
- Content-Type: application/json
- Body: This is typically empty, but some APIs will require additional information in the body
- Typically Empty
A company’s API typically includes documentation that describes the interactions and expected responses with each API endpoint. The endpoint is commonly human-readable to give an indication of the type of data that it provides and the values of parameters being passed. Here is an API request example using Google Maps:
- API endpoints follow a general format of:
- https://baseurl.com/api/endpoint?parameters
- API endpoint example: Request a Static Map centered on ‘Brooklyn Bridge in NYC’ with zoom =13, image size of a 600×300 pixels and a roadmap layer
- GET https://maps.googleapis.com/maps/api/staticmap?center=Brooklyn+Bridge,New+York,NY&zoom=13&size=600×300&maptype=roadmap&key=YOUR_API_KEY
- This is the Google Maps API URL: https://maps.googleapis.com/maps/api/
- This is the specific endpoint to append to API URL for static maps: /staticmap?
- Similarly, to get an image of a street view you’d append: /streetview?
- For directions you’d append: /directions?
- After the question mark, input all the parameters used to tailor and specify details on the request
- center ← where to center the static map
- zoom ← how much zoom
- size ← how large or small do you want the response image
- maptype ← satellite, roadmap?
- At the end of the request is one last parameter called Key:
- This is referred to as an API Key, and it is part of verifying the user when they signed up to use the API
- Sometimes the Key is passed along in the Header of the request
- Here is the response of the API request example:
- GET https://maps.googleapis.com/maps/api/staticmap?center=Brooklyn+Bridge,New+York,NY&zoom=13&size=600×300&maptype=roadmap&key=YOUR_API_KEY
In the example above, an image was returned from the API HTTP Request. APIs also commonly return data in one of two formats: JSON (JavaScript Object Notation) and XML (extensible markup language). To visualize the difference, below is a table of venues along with their latitude and longitude, which will then be represented in JSON and XML respectively.
Venue Table
Venue Table (JSON Format)
Venue Table (XML Format)
With both JSON and XML, responses can be parsed to transform the data into a tabular format for processing in Excel or Python. Thus, APIs enable developers to programmatically access data and easily integrate it into existing workflows. The enhanced data accessibility from API also exposes the data to a broader audience, which may lead to new and exciting applications.