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.

How to use the API?

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.

Supported languages

OSDG supports 15 languages so that you can discover your SDG impact in your native language.

Cite us

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

Rate limits

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:

1. Limit requests rates

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.

2. If the service slows down, allow time to clear the cache

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.

Our API in action

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!

Text snippet

            
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)
            
        

PDF documents

            
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)

            
        

Check remaining credits

              
  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 Wheel

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',
}

Contact us

If you are having issues with the OSDG API, please contact our support team.