API

General Access

To access the GlobalView API, you'll first need an Okta account. Once you've used that to log in, you'll receive an API key. You can use that API key to access the wiki using any mediawiki library.

For the purpose of this document, we'll use the python mwclient library referenced at: https://mwclient.readthedocs.io/

A simple test that your account is working follows, replacing the USERNAME and API_KEY sections with the ones provided:

import mwclient
site = mwclient.Site('torque.leverforchange.org/', 'GlobalView/', scheme="https")
site.login("<USERNAME>", "<API_KEY>")
print(site.api('torquedataconnect', format='json', path='/competitions'))

The above should print out something like:

OrderedDict([('result', ['LLIIA2020', 'LFC100Change2020', 'LFC100Change2017', 'EO2020', 'RacialEquity2030', 'Climate2030', 'ECW2020', 'LoneStar2020'])])

Using mwclient

If you want to use the mwclient library to interface with mediawiki, the following documents how. This is also how you would interface if using a different language, replacing the python mwclient calls with the closest appropriate analogue in your language choice.

MediaWiki API

Because the torque API is fronted by mediawiki api, there are a few small changes from how APIs are generally created.

When calling the api, call the action 'torquedataconnect'. You can call with the format 'json' or 'xml', depending on what your library would like to use. For python, both get converted to an OrderedDict, and this document uses 'json'.

All responses are json objects with a single key "result", with the value being dependent on the endpoint, as described below. So for the following documentation, you can assume that you will always need to get response["result"]

Endpoint Reference

/competitions

Returns list of competitions available. Each competition is a String

Example python:

response = site.api(
    'torquedataconnect',
    format='json',
    path='/competitions'
)

print(response["result"][0]) # Get the first competition

/competitions/<COMPETITION>

Returns the following json object:

result -> {
  name: competition name, a string
  fields: fields available, a list of strings
  last_updated: ISO format of the last time any data in this competition was updated, a string
}

Example python:

response = site.api(
    'torquedataconnect',
    format='json',
    path='/competitions/LoneStar2020'
)

print(response["result"]["fields"][0]) # Get the first field

/competitions/<COMPETITION>/proposals

Where COMPETITION is one of the available competitions returned by '/competitions' above.

Returns a list of all proposals ids available, which are strings. These are ordered in natural ordering for the competition (sometimes by organization name, sometimes by other fields).

Example python:

response = site.api(
    'torquedataconnect',
    format='json',
    path='/competitions/LoneStar2020/proposals'
)

print(response["result"][0]) # The first proposal 

/competitions/<COMPETITION>/proposals/<PROPOSAL_KEY>

Where COMPETITION is one of the available competitions, and PROPOSAL_KEY is one of the keys returned by .../proposals above

Returns a json object, where the keys are each fields (which are available as a list from the competition lookup above), and the values are the data for this proposal

Example python:

response = site.api(
    'torquedataconnect',
    format='json',
    path='/competitions/LoneStar2020/proposals/410'
)

print(response["result"]) # Print the whole proposal!

/competitions/<COMPETITION>/proposals/<PROPOSAL_KEY>/fields/<FIELD>

Where COMPETITION, PROPOSAL_KEY are similar to above, and FIELD is one of the field names return as above.

Returns a string for that specific field in this proposal, in this competition.

Example python:

response = site.api(
    'torquedataconnect',
    format='json',
    path='/competitions/LoneStar2020/proposals/410/fields/Application #'
)

print(response["result"]) # Prints 410

/search

Takes in a secondary parameter, "q" which is the query for searching. Returns a list of URIs that represent proposals for which this query matchines. The order is in descending order of relevance.

response = site.api(
    'torquedataconnect',
    format='json',
    path='/search',
    q="water in india"
)

top_search_result_uri = response["result"][0]
top_search_result = site.api(
    'torquedataconnect',
    format='json',
    path=top_search_result_uri
)["result"]
print(top_search_result) # Outputs the whole result

/competitions/<COMPETITION>/search

The same as above, but for a specific competition

Example python:

response = site.api(
    'torquedataconnect',
    format='json',
    path='/competitions/LoneStar2020/search',
    q="water in india"
)

top_search_result_uri = response["result"][0]
top_search_result = site.api(
    'torquedataconnect',
    format='json',
    path=top_search_result_uri
)["result"]
print(top_search_result) # Outputs the whole result