Welcome to the OSDG API – a tool to detect and label SDG-relevant content in text and documents. OSDG is a partnership between PPMI, UNDP SDG AI Lab, and a growing community of researchers led by Dr. Nuria Bautista Puig.
The API can accept two types of input: text snippets and PDF documents.
The OSDG API is created to label texts which are longer than a paragraph.
NB! A text snippet or a PDF document must contain at least one paragraph longer than 10 words. However, to get higher quality results, submit longer texts (3 paragraphs or more). Shorter texts will not receive SDG labels.
The number of eligible text segments found in the text snippet, or a PDF document can be found in the result retrieved from the API.
OSDG supports 15 languages so that you can discover your SDG impact in your native language.
If you plan to use the API for your research, you can cite the tool as indicated below.
OSDG, UNDP IICPSD SDG AI Lab, & PPMI. (2022). OSDG.ai. https://osdg.ai
OSDG API is a research tool, not an industrial-strength digital solution. The underlying server is relatively small and can get overwhelmed by a massive amount of requests.
Exceeding a rate of 3 requests per second for snippets or 1 request per second for pdf documents will result in an error response.
To avoid such situations you can do the following:
To prevent the API from being overwhelmed, introduce a wait time between each request. For requests that require translation, please introduce longer wait times. If you are batching your requests, please introduce longer breaks between batches.
The OSDG API uses an internal cache, which stores the results before they are retrieved. Large volumes of requests can overload the cache, causing the entire service to slow down. If that happens stop calling the API for ~1 hour for the cache to auto-clear. Then reduce the batch size, and increase the time between requests and wait times between batches.
The OSDG API is already used by researchers and sustainability advocates at large. See a few existing applications below.
Launched your own project using OSDG API? Share it with us!
import requests
import json
API_TOKEN = ""
text = """Using satellite data on deforestation and weather in Malawi and linking those datasets with household survey datasets,
we estimate the causal effect of deforestation on access to clean drinking water.
In the existing literature on forest science and hydrology, the consensus is that deforestation increases water yield.
In this study, we directly examine the causal effect of deforestation on households’ access to clean drinking water.
Results of the two-stage least-squares (2SLS) with cluster and time fixed-effect estimations illustrate strong empirical evidence that deforestation decreases
access to clean drinking water.
Falsification tests show that the possibility of our instrumental variable picking up an unobserved time trend is very unlikely.
We find that a 1.0-percentage-point increase in deforestation decreases access to clean drinking water by 0.93 percentage points.
With this estimated impact, deforestation in the last decade in Malawi (14%) has had the same magnitude of effect on access to clean
drinking water as that of a 9% decrease in rainfall."""
url = "http://20.73.166.85/label_text
payload = {"text": text}
headers = {"token": API_TOKEN}
response = requests.post(url, json=payload, headers=headers)
if response.status_code == 200:
sdg_labels = response.json()
else:
# Something went wrong with the request
print(response.text)
import requests
import json
API_TOKEN = ""
with open("document.pdf", "rb") as f:
document = f.read().decode("latin-1")
url = "http://20.73.166.85/label_document"
payload = {"document": document}
headers = {"token": API_TOKEN}
response = requests.post(url, json=payload, headers=headers)
if response.status_code == 200:
sdg_labels = response.json()
else:
# Something went wrong with the request
print(response.text)
import requests
import json
API_TOKEN = ""
url = "http://20.73.166.85/check_credits"
headers = {"token": API_TOKEN}
response = requests.get(url, headers=headers)
if response.status_code == 200:
credits_remaining = response.json()
print(credits_remaining)
else:
# Something went wrong with the request
print(response.text)
OSDG has recently introduced the OSDG Wheel, a detailed breakdown of all SDGs discovered within a text input or a PDF file. All identified Goals are expressed in proportion to their estimated relevance scores and add up to 100%.
Use this data to inspect linkages to other SDGs, or create easy visual representations through charts, like pie charts or stacked columns.
The example below shows a case where the document’s key SDG label is SDG 16. In the OSDG Wheel, the Goal has an estimated relevance score of 88,46% with additional linkages to SDG 8 (7,69%) and SDG 6 (3,85%).
{
number_of_text_segments: 13,
number_of_eligible_text_segments: 13,
number_of_distinct_segments_w_sdg_labels: 9,
'sdg_intensity (%)': 90,
document_sdg_labels: [['SDG_13', 89]],
sdg_wheel: [
{ sdg: 'SDG_6', share: 3.85, terms: ['water security'] },
{
sdg: 'SDG_13',
share: 88.46,
},
{ sdg: 'SDG_8', share: 7.69,
],
status: 'Completed',
}
If you are having issues with the OSDG API, please contact our support team.