How to use an API without programming
No matter if you’re a digital marketer, data analyst or growth hacker — getting data from an API is a super-power. This is how you can get data from an API without being a developer or knowing programming.
If you identify as a digital marketer, growth hacker, growth marketer, or any combination of these, you are using data every day to get insights and evaluate what you do. Sometimes this data is only accessible using an API, and without knowing how to code, it may feel intimidating just looking at the API documentation.
In this article, you are going to learn:
- What an API is and get the necessary information to use it
- How to access an API using an API key
- How to retrieve data from an API
- How to work with JSON data
- How to convert JSON into CSV, to enable import into a spreadsheet
Some basic knowledge of how to use the Terminal may be beneficial (see the last section of the article for links where to learn more).
For the purpose of demonstrating a real-life example, we’re using the Mailchimp API in this article.
Introduction to APIs
The purpose of an API, an Application Programming Interface, is to give outside access to the data and inner workings of a system. It may be to allow retrieval of data, or receiving data or commands that trigger an action.
The most common style of APIs is called REST. It works in the same way as you interact with a web page — but instead of requesting a page by clicking a link, you retrieve data by making a request to an URL. Typically data is returned as JSON.
What you need before you start
Before attempting to use a service’s API you should locate its API documentation. If the API is publicly accessible, there will be documentation available. Often it may not be the most prominent thing featured on the webpage — look in the footer for a link, or for a page named Developers.
Look for a Getting Started section or similar, and especially where access or authentication is mentioned. You need to find out how to access the API, typically you need some kind of API key or token, and the documentation will tell you how to obtain that.
How to access an API
Depending on the intended use of an API, the way to access it may differ, but there are a couple of standard methods.
In this article, you as a user of the service will access your own data. In this case, it is common to access the API using some type of API key.
Another scenario is that you as a developer want to create an application that will access and process data on behalf of users. In this scenario, something called OAuth2 is commonly used (this is something that is not covered in this article).
In this article, we are using Mailchimp’s API, where you may generate an API key on your Account Extras page. This is how an API key may look like:
Note the ending, usXX (we need this number later, in our API requests).
The API key must be included in every request you make to the API. It does authenticate your request and allows you to access your data (and possible any public data), but no one else’s. In all examples in this article, replace the API key with your own.
Common ways to include an API key is as an URL parameter, a header field or, as in the case of Mailchimp, using Basic Authentication.
Before getting more technical, we’ll have to look at one of the essential pieces of working with an API — the URL.
The URL demystified
The URL is the most fundamental part of accessing an API since it does point to what resource it is we want to request the data from. This is how a URL is constructed:
This is an example of an URL used to access lists in the Mailchimp API (except the parameters, which is added just for demonstration). Here is an overview of the different parts.
- Protocol. When accessing an API, this is pretty much always https (https require that requests are made over a secure connection).
- Host. The host is the website address. Consists of an optional subdomain (or several), domain name and top-level domain (for example .com or country-code)
- Path. An optional path, starting with a slash
/, typically determines which resource of the API to access. Here it is also used to specify the version of the API to use
- Parameters. The optional parameters (also called query string) are preceded by a question mark. Parameters are sent to the host in the form of attribute-value pairs separated by an ampersand
Retrieve data from an API
Data is requested and retrieved from the API using HTTP requests. HTTP is the same protocol as your web browser is using to request the content of a page when you visit a website.
There are a couple of different types of HTTP requests; usually referred to as HTTP methods. The two most common ones are:
- GET — to request and retrieve data.
- POST — typically used to make a change or create something in the API.
There are other HTTP methods, but in this article, we limit the scope to GET and getting data.
When we make a request to the API using HTTP, we use an URL to point to the resource we want to get, and we authenticate by providing our API key.
It is not needed to follow this article, but if you want to see all the available resources and details on how to request them — everything is in the Mailchimp API Reference.
Example: Get information about all Mailchimp lists
By looking in the API documentation, we see that it is possible to retrieve information about all lists (also referred to as audiences) in your account, including statistics like the number of list members, by making a GET /lists request.
The documentation does also mention that the domain to use in a request depends on the last part of your API key, which corresponds to the data-center used by your account. As an example — if the last part is
us20 then the domain to use is
https://us20.api.mailchimp.com/3.0/. This is specific to the Mailchimp API and not something that is generally seen in API.
Now it is time to request data from the API. This is done by using curl in your Terminal window. In macOS curl is installed by default, so there is no need to download anything.
Type the following in your terminal to execute the API request using curl:
curl -u 'firstname.lastname@example.org:34f59ffc895fb65e6b80f11b5770a092-us20' https://us20.api.mailchimp.com/3.0/lists
The result is displayed in your terminal.
Congratulations — you’ve just made your first successful API request. All the “code” you see mixed up with strings of text is called JSON.
Working with JSON data
Looking at JSON without and line-break or formatting is hard. By making use of the command-line tool jq (installation needed) we can apply formatting to make it easier to read — in the terminal, append
| jq . to the previous command-line.
curl -u 'email@example.com:34f59ffc895fb65e6b80f11b5770a092-us20' https://us20.api.mailchimp.com/3.0/lists | jq .
This very powerful technique of channeling output from one tool as input to another is called piping (note the use of pipe-character|).
Here’s how the formatted JSON result of the
/lists request looks like:
Convert JSON to CSV
Formatting makes it a lot easier to manually read JSON, but it does not help with importing the data into a spreadsheet. The jq tool comes to the rescue once again.
The output is an array of objects, where each object is representing a Mailchimp list. Each list object does have a
stats property that itself is an object with properties like
open_rate, etc. Let's use the jq tool to convert the values into a CSV format, that then may be imported into a spreadsheet (CSV stands for comma-separated values and is a file format that spreadsheet software like Google Sheets and Excel may import).
The jq tool may convert an array into CSV. Because we’re only interested in a few values, we first need to point them out and restructure them as an array. Exactly why the following command-line looks like it does, is out of scope for this article, and is covered in the documentation of jq.
curl -u 'firstname.lastname@example.org:34f59ffc895fb65e6b80f11b5770a092-us20' https://us20.api.mailchimp.com/3.0/lists | jq '.lists | .stats | [ .member_count, .unsubscribe_count, .open_rate ] | @csv'
Which results in:
It is the member count, unsubscribe count, and open rate each separated by a comma. If your Mailchimp account has multiple lists/audiences, the result will contain multiple rows.
Save output as a file
To enable import of the data into a spreadsheet, we redirect the command-line output using a stream into a file we name
curl -u 'email@example.com:34f59ffc895fb65e6b80f11b5770a092-us20' https://us20.api.mailchimp.com/3.0/lists | jq '.lists | .stats | [ .member_count, .unsubscribe_count, .open_rate ] | @csv' > liststats.csv
This is done by appending
> liststats.csv to the end. The file will be created in your current directory. If you want to append the output to an existing file instead of creating a new one, you use
>> liststats.csv (i.e., two
Now you can import the file into your preferred spreadsheet application and continue to manipulate the data there.
Where to go to learn more
The purpose of this article is to demonstrate how to get data from an API, with no programming skills and limited technical knowledge into a file for further manipulation in familiar tools. Hopefully, this has demonstrated the power and potential to continue to learn.
The following tools and tutorials will help you along taking the next steps, building upon what you have learned in this article:
- Postman — is a tool that makes it easier to experiment, test, and interact with an API.
- jqplay — is an interactive playground to test and learn about jq.
- Learn the Command Line — Basic command-line knowledge is essential, and this Codecademy tutorial is a great place to start.
- Mailchimp API Playground — to experiment with the Mailchimp API, there’s a playground that allows you to make API requests in your browser.
Another example of how to make use of an API, without programming, for automating tasks is described in the article Automating Link Tracking for Digital Marketers.
Stefan is CTO and co-founder at Relatable. Relatable is a marketing tech company specialized in influencer marketing. Through clever use of technology and automation, we create large-scale word of mouth marketing with the most creative and influential people around the world. Check out our current job openings to join us, or our case studies for examples of what we do.