API Docs
Digital Gender Gaps API (v1)
The Digital Gender Gaps API allows you to access all data displayed at digitalgendergaps.org. This provides a way to automate data requests for individual countries, specific dates, or bulk downloads. We aim to update our data once per month and to make them openly available for free. Web developers can use this API to develop web applications that query our database on-the-fly based on the needs of your users.
Overview of all endpoints
./api/v1/init
Returns data needed to initialize the web application.
./api/v1/query_specific_country
Returns digital gender gap estimates for all dates for a single country.
See below for a list of required arguments.
./api/v1/query_national
Returns digital gender gap estimates for all countries for a single
date. See below for a list of required arguments.
./api/v1/download_data_with_dates
Returns digital gender gap estimates for all countries within a range of
dates. See below for a list of required arguments.
./api/v1/write_national
Writes new digital gender gap estimates into the database for a single
country and date. See below for a list of required arguments.
Endpoint: init
Returns data needed to initialize the web application
including:
- A list of countries with data
- A list of dates with data
- Descriptions of each indicator used to measure digital gender
gaps
- Types of indicators (e.g. mobile phone access, internet access)
- Colour palette for mapping results
- Contact email address
Example query
http://digitalgendergaps.org/api/v1/init
Note: Click the link above and paste the JSON response here to view it in a cleaner format.
Arguments
None
Response
The JSON response includes the following elements:
Response | Description |
---|---|
countries | A list of all countries with data. This includes country names and ISO-2 country codes. |
dates | A list of dates with data formatted as YYYYMM. |
models | An object containing descriptions of all indicators (i.e. models) including their name, formatted name, type, description, and display order. |
types | A list of indicator types (e.g. mobile, internet). |
palette | Colour palette for mapping results including colour hex codes, break point, legend title, subtitles, and labels. |
contact | A contact email address. |
status | http status code. |
message | Status message. |
Endpoint: query_specific_country
Returns data for all dates from a single country.
Example queries
http://digitalgendergaps.org/api/v1/query_specific_country?iso2code=GB
Note: Click the links above and paste the JSON responses here to view them in a cleaner format.
Arguments
Argument | Description |
---|---|
iso2code | (required) Country as a two character ISO-2 country codes. |
model | (optional) List of indicators to return. Note: Get possible values from keys of the “model” element returned from the “init” endpoint. |
Response
The JSON response includes the following elements:
Response | Description |
---|---|
data | Digital gender gap estimates for each indicator and date. |
status | http status code. |
message | Status message. |
Endpoint: query_national
Returns data for all countries for a single date.
Example queries
http://digitalgendergaps.org/api/v1/query_national?date=202206
Note: Click the links above and paste the JSON responses here to view them in a cleaner format.
Arguments
Argument | Description |
---|---|
date | (required) Date in format YYYYMM. |
model | (optional) List of indicators to return. Note: Get possible values from keys of the “model” element returned from the “init” endpoint. |
Response
The JSON response includes the following elements:
Response | Description |
---|---|
data | Digital gender gap estimates for each indicator and date. |
message | Status message. |
status | http status code. |
Endpoint: download_data_with_dates
Returns data for all countries within a range of dates.
Example query
http://digitalgendergaps.org/api/v1/download_data_with_dates?start_date=202206&end_date=202207
Note: Click the link above and paste the JSON response here to view it in a cleaner format.
Arguments
Argument | Description |
---|---|
start_date | (required) Initial date in range in format YYYYMM. |
end_date | (required) Last date in range in format YYYYMM. |
pretty_names | (optional) Return formatted column names (boolean; default = True) |
Response
The JSON response includes the following elements:
Response | Description |
---|---|
data | Digital gender gap estimates for each country, date, and indicator. |
message | Status message. |
status | http status code. |
Endpoint: write_national
Writes new digital gender gap estimates into the database for a single country and date.
Example query
http://digitalgendergaps.org/api/v1/write_national?token=XXXXX&iso2=GB&date=202210&Ground_Truth_Internet_GG=0.5
Note: This endpoint requires an access token and is not available for public access.
Arguments
Argument | Description |
---|---|
token | (required) Access token. |
date | (required) Date in format YYYYMM. |
iso2 | (required) Country as a two character ISO-2 country code. |
internet_online_offline_model_prediction | (optional) Value to write into database for this indicator. |
internet_offline_model_prediction | (optional) Value to write into database for this indicator. |
ground_truth_internet_gg | (optional) Value to write into database for this indicator. |
mobile_online_model_prediction | (optional) Value to write into database for this indicator. |
mobile_online_offline_model_prediction | (optional) Value to write into database for this indicator. |
mobile_offline_model_prediction | (optional) Value to write into database for this indicator. |
ground_truth_mobile_gg | (optional) Value to write into database for this indicator. |
Response
The JSON response includes the following elements:
Response | Description |
---|---|
message | Status message. |
status | http status code. |
Query API from Python or R
Python
# import packages
import requests
import pandas as pd
# query arguments
args = {
"iso2code": "AT"
}
# submit query as GET request
response = requests.get(url = 'http://digitalgendergaps.org/api/v1/query_specific_country',
params = args)
# format response as dictionary
response = response.json()
# check status
print(response.get('status'))
print(response.get('message'))
# extract data as pandas dataframe
if response.get('status') == 200:
data = pd.DataFrame(json.loads(response.get('data')))
R
# import packages
library('httr')
library('jsonlite')
options(scipen = 999)
# query arguments
args <- list(iso2code = "AT")
# submit query as GET request
response <- httr::GET(url = 'http://digitalgendergaps.org/',
path = 'api/v1/query_specific_country',
query = args)
# format response as list
response <- jsonlite::fromJSON(httr::content(response, as='text'))
# check status
print(response$status)
print(response$message)
# extract data in various formats
if(response$status == 200){
# json string
data <- response$data
# json -> list of lists
data <- jsonlite::fromJSON(data)
# list of lists -> data.frame with cells containing lists
# note: this is a convenient format for dealing with JSONs for some data.frame cells in R.
data <- as.data.frame(do.call(cbind, data))
}