The authorization token can be used to authenticate when getting data from any of the GO API endpoints. Authorization token enables to access the data that is not public. Data can still be accessed without using authorization token, however only the public data will be visible. Here we show how can you access the data corresponding to events in regions or countries.
¶ Using authorization token in Power BI/ Excel
The API can be accessed by building a URL query in Power BI/ Excel. We start with the base URL to access the database and then set the parameters to select just the data that we need. In this example we will be accessing the Events and then set the parameters regions__in (integer) to 2 (Asia Pacific) and then set the countries__in (integer) parameter to 84 (country id) so as to access the events occurring in India. The regions__in parameter can take values from 0 to 4 (integer) where 0 corresponds to “Africa”, 1 corresponds to “Americas”, 2 corresponds to “Asia Pacific”, 3 corresponds to “Europe” and 4 corresponds to “Middle East & North Africa”.
So our URL for this particular search would like this:
https://goadmin.ifrc.org/api/v2/event/?regions__in=2&countries__in=84
- Here
https://goadmin.ifrc.org/api/tells PowerBI (or any other service/tool referencing the API) to connect with the GO server. All of your API calls to GO will start with this as a base URL. - The
v2/event/refers to the latest version of the API. There are multiple data tables within the database and event tells GO to search for the table that stores events data ( as opposed to , say appeals, or the deployments. See https://goadmin.ifrc.org/api-docs/swagger-ui/ to see a full list of the available API endpoints. - The
?regions__in=2&countries__in=84are the 2 parameters that have been used to filter out the data for a particular region and country. The parameters are telling us to return the data corresponding to the Asia Pacific region and India. countries__in takes an integer and it corresponds to the country id. The country id of India is 84.
¶ Getting your data in PowerBI/ Excel
To get your data in PowerBI/ Excel using the authorization token proceed with the following steps:
- Open PowerBI/ Excel and select Get Data from the top ribbon, and then select Web.
- Select the Advanced option from the window that appears.
- Under the URL parts option, add the base URL in the first box and the URL corresponding to the parameters in the second box.
- Once you have added both the URL parts, you will be able to see the complete URL that will be used for querying the data under the URL preview option.
- To use the authorization token you will have to enter the authorization token under the HTTP request header parameters option. In the box on the left side type Authorization and in the right box type Bearer followed by your authorization token and then click OK.
- If the authorization token is valid this will open a new window called Power Query editor where you can organize the data that is returned in preparation for visualization.
- Upon clicking OK the Power query editor opens and a bunch of transformations are already applied by Power Query. It is a good idea to give your query a name before you start bringing a lot of queries. So on the left pane with query selected, look at the right side of the window and rename it to something like India Events.
- The data comes into PowerBI in JSON format, which makes transferring the data easy, but can be difficult to easily interpret. Our India Events has returned 50 lines of data and we are accessing the data from the first page of the API (see the section named
Paginationto access data from all the pages in the API endpoint). - We can expand the other columns like results.countries. The results.countries is a placeholder for the data for that particular country. Click on the button right to the column name and select Expand to New Rows. Similarly you can expand any other columns which were not expanded by the Power Query.
- Click again on the button on the right side of the column name and a dialog box will appear showing the data fields available. You can select any number of fields and then click ok.
- Now we are able to see the data which this query is actually providing us. Click on Close and Apply at the top of your Power Query editor window. Now our data is ready for building visuals.
¶ Using authorization token in python
We can also use python for extracting data from any GO-API endpoint. We use the python code below to obtain data from the Event API endpoint. Since the API is paginated, the python code below shows how to get the data from the first page.
import requests
import pandas as pd
api_url = "https://goadmin.ifrc.org/api/v2/event/"
auth_token = "Your authorization token"
First we import the necessary python packages and specify the API URL and authorization token.
requests: Used for sending HTTP requests and handling responses, commonly used for web scraping, API interaction, and downloading web content.pandas: Provides data structures and data analysis tools for working with structured data.
def fetch_data(limit=50, offset=0, regions__in=None, countries__in=None):
params = {"limit": limit, "offset": offset}
if regions__in or countries__in:
params["regions__in"] = regions__in
params["countries__in"] = countries__in
headers = {"Authorization": f"Bearer {auth_token}"}
response = requests.get(api_url, params=params, headers=headers)
if response.status_code == 200:
return response.json()
else:
print(f"Failed to fetch data. Status code: {response.status_code}")
return None
# Fetch data from the first page
first_page_data = fetch_data(limit= 50, offset=0, regions__in="2")
if first_page_data:
# Process the data from the first page
results = first_page_data.get('results', [])
# Do whatever you need to do with the results
df = pd.Dataframe(results) # convert the JSON object into pandas dataframe We define a fetch_data function to obtain data from the API. Inside the fetch_data function, we specify the authorization token in the headers dictionary.
In order to get the data from any other page, we can change the offset value. Offset value of 0 suggest that the data is coming from the first page. Incrementing the offset by 50 will allow the code to access the data from subsequent pages. Limit tells how many records to display. For example if we want data from the second API page we need to set the offset as 100. In general the fallowing formula can be used to set the value of Offset when accessing data from any API page.
Offset = (Page_num) - 1 * 50