360Giving API Documentation

Getting Started

Try the 360 Giving API in the Browser with Swagger UI

Try the API interactively in the browser with Swagger UI.

Swagger UI details the response schema for each endpoint.

Using the 360Giving API with cURL

Example cURL command to fetch from the Organisation Detail endpoint. Note the header Accept: application/json must be set.

curl --header "Accept: application/json" "https://api.threesixtygiving.org/api/v1/org/GB-CHC-1164883/"

Result (formatted):

{
  "self": "https://api.threesixtygiving.org/api/v1/org/GB-CHC-1164883/",
  "grants_made": "https://api.threesixtygiving.org/api/v1/org/GB-CHC-1164883/grants_made/",
  "grants_received": "https://api.threesixtygiving.org/api/v1/org/GB-CHC-1164883/grants_received/",
  "funder": null,
  "recipient": {
    "aggregate": {
      "grants": 29,
      "currencies": {
        "GBP": {
          "avg": 169309.8275862069,
          "max": 745000,
          "min": 2000,
          "total": 4909985,
          "grants": 29
        }
      }
    }
  },
  "publisher": null,
  "org_id": "GB-CHC-1164883",
  "name": "360 Giving"
}

Using the 360Giving API with Python requests

import requests

response = requests.get("https://api.threesixtygiving.org/api/v1/org/GB-CHC-1164883/", headers={"Accept": "application/json"})
response.raise_for_status()
print(response.json())

(same response as cURL example)

Next Steps

Check out more examples, read the notes and best practices, and register for important API updates.

Notes and Best Practices

Authentication

The API provides read-only access to open datasets, and no authorization is required to use it. All endpoints can be used without needing to provide an authentication token of any kind.

Headers

The API requires all requests to set the Accept header to application/json. This is shown in the Python and cURL examples above, for other tools check the tool documentation for how to set headers.

Self Links

Organisation objects, or objects that refer to an Organisation, contain a self attribute which is a URL that both uniquely identifies the Organisation and can be requested to fetch the Organisation’s details. The self link can serve as an additional or alternative identifier to Org Id for an application’s own use.

Org Ids

Org Id is a database of registers (lists) of unique identifiers for organisations around the world. By combining a prefix (scheme) and a register identifier, a globally unique identifier for an organisation can be created. For more info, see https://org-id.guide/about.

360 Giving data largely contains identifiers for charities, companies, government and research organisations in the UK. Here are some Org Id prefixes (schemes) commonly found in 360 Giving data:

Scheme / Prefix	Register	Example
`GB-CHC`	Charity Comission of England & Wales	`GB-CHC-1164883` from charity number 1164883.
`GB-SC`	Scottish Charity Register	`GB-SC-SC000470` from Scottish charity number SC000470.
`GB-NIC`	Charity Comission for Northern Ireland	`GB-NIC-100818` from Northern Ireland charity number 100818.
`GB-COH`	Companies House	`GB-COH-09668396` from company number 09668396
`XI-ROR`	Research Organisation Registry	`XI-ROR-05v62cm79` from https://ror.org/05v62cm79
`GB-GOR`	Government Organisation Register	`GB-GOR-PC390` for the National Lottery Heritage Fund

To find an Org Id for a specific organisation, a good place to start is search FindThatCharity or GrantNav.

Pagination

Some endpoints return a large set of results i.e. the Grants Made, Grants Received and Organisation List endpoints. To improve performance, the results from these endpoints are broken up into pages, such that multiple requests may by needed to fetch the entire set of results.

Paginated endpoints accept limit and offset parameters to control which subset of results are returned. The limit defines how many results are returned in the requested page, and offset the the offset into the whole list of results to begin the page.

Check the individual endpoint documentation to find the maximum size of limit.

Example Paginated Response:

{
  "count": 28,
  "next": "https://api.threesixtygiving.org/api/v1/org/GB-CHC-1164883/grants_received/?limit=10&offset=20",
  "previous": "https://api.threesixtygiving.org/api/v1/org/GB-CHC-1164883/grants_received/?limit=10",
  "results": [
     ...
  ]
}

The top-level object of a paginated response contains four attributes count, next, previous and results. The count is the total size of the whole result set. The next and previous attributes are the URLs to follow to fetch the next and previous results. They will be null if no next or previous page exists i.e. the end or beginning of the result set. results contains the array of results for this page.

The recommended way to fetch all results from a paginated endpoint, is to start by requesting the base URL e.g. https://api.threesixtygiving.org/api/v1/org/GB-CHC-1164883/grants_received/ and then continue to fetch the next URL in a loop, until next is null.

Rate Limiting

Requests are limited to 2 requests per second per IP address. Requests that exceed this limit will be met with a 429 Too Many Requests HTTP response.

This limit is in place to ensure the stability and cost-effectiveness of our service. If an application exceeds the limit, it should wait at least half a second before continuing.

If your use case could benefit from exceeding this limit, please get in contact with support to discuss your application’s requirements.

Error Handling

The most common errors likely to be returned by the API are 404 Not Found or 429 Too Many Requests.

A 404 Not Found response is generated by the Organisation Detail, Grants Made or Grants Received endpoints if the provided Org Id is not found in the 360 Giving database. Check the Org Id for mistakes, or try to find the organisation on GrantNav. If the organisation exists on GrantNav but not the API, get in touch with support as this may be in error.

The 429 Too Many Requests response is generated when the application exceeds it’s requests-per-second limit, see Rate Limiting.

An application should handle these errors appropriately, e.g. inform the user of an organisation not found, or reducing the frequency of requests in response to a rate limit.

Caching and Data Retention

Caching frequently used data is a common method to improve application performance. Data presented by the 360 Giving API is updated once per day, overnight on UK time (typically between midnight and 6am, but this isn’t guaranteed). If an application caches or otherwise saves data, it’s recommended to clear the cache overnight, or retain a copy of data only until the following day.

If your application caches or retains data for longer than this, please subscribe to our mailing list to be notified of take-down requests.

Versioning

The API version forms part of the URL. Currently there is only v1, so all requests should be directed to /api/v1/....

In future, new major versions with breaking changes will be hosted at different URLs, with the existing versions continuing to exist for at least a grace period, to enable backwards compatibility with existing applications using older versions and give time for developers to update to new versions.

The current API version may still change in minor ways, signup to the mailing list for updates on any changes to the API.

Testing

As the 360 Giving API provides read-only access to the data, no separate testing/staging environment is necessary. Use the live API to test scripts or applications, making sure to adhere to the rate limit.

Terms of Use

See the API Terms and Conditions here.

Take-down Requests

Please register to be notified of take-down requests, and act quickly to remove data in response to requests. For more information, see the 360Giving Take-down policy.

Endpoints

Organisations List

GET /v1/org/

The Organisations List endpoint returns a paginated list of all the organisations known to exist in 360 Giving data, including both funders and recipients of grants. It returns the Org ID and name for each organisation, plus a self link to the Organisation Detail endpoint.

Query Parameters:

Parameter	Type	Required	Description
`limit`	integer	No	Number of results to return per page. Maximum 1000.
`offset`	integer	No	The starting index from which to return the results.

Example Request:

GET /v1/org/?limit=1000&offset=2000

Example Response:

{
    "count": 391426,
    "next": "https://api.threesixtygiving.org/v1/org/?limit=1000&offset=3000",
    "previous": "https://api.threesixtygiving.org/v1/org/?limit=1000&offset=1000",
    "results": [
        {
            "self": "https://api.threesixtygiving.org/v1/org/GB-CHC-1080833/",
            "org_id": "GB-CHC-1080833",
            "name": "Allonby Village Hall"
        },
        {
            "self": "https://api.threesixtygiving.org/v1/org/GB-CHC-1080835/",
            "org_id": "GB-CHC-1080835",
            "name": "Ventnor Botanic Garden Friends' Society"
        },
        {
            "self": "https://api.threesixtygiving.org/v1/org/GB-CHC-1080837/",
            "org_id": "GB-CHC-1080837",
            "name": "PRS Foundation"
        },
        {
            "self": "https://api.threesixtygiving.org/v1/org/GB-CHC-1080838/",
            "org_id": "GB-CHC-1080838",
            "name": "WILD GROUND"
        },
        ...
    ]


}

Organisation Detail

The Organisation Detail returns extra detail about an organisation, including whether the organisation is a funder or recipient of grants, and statistics about their grants.

GET /v1/org/<org_id>/

Query Parameters

This endpoints accepts no query parameters.

Example Request

GET https://api.threesixtygiving.org/v1/org/GB-CHC-1164883/

Example Response

From this example response, we know this organisation is a recipient but not a funder because the recipient sub-object is populated but the funder sub-object is null, and they’ve received a total of 29 grants that have been published in 360 Giving datasets. This organisation is a charity because it’s org_id begins with the GB-CHC prefix corresponding to a charity registered with the charity commission of England and Wales (see https://org-id.guide/list/GB-CHC).

{
  "self": "https://api.threesixtygiving.org/v1/org/GB-CHC-1164883/",
  "grants_made": "https://api.threesixtygiving.org/v1/org/GB-CHC-1164883/grants_made/",
  "grants_received": "https://api.threesixtygiving.org/v1/org/GB-CHC-1164883/grants_received/",
  "funder": null,
  "recipient": {
    "aggregate": {
      "grants": 29,
      "currencies": {
        "GBP": {
          "avg": 169309.8275862069,
          "max": 745000,
          "min": 2000,
          "total": 4909985,
          "grants": 29
        }
      }
    }
  },
  "publisher": null,
  "org_id": "GB-CHC-1164883",
  "name": "360 Giving"
}

Grants Made by an Organisation

The Grants Made endpoint returns a paginated list of all known grants made by the given funding organisation.

/v1/org/<org_id>/grants_made/

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Number of results to return per page. Maximum 1000.
`offset`	integer	No	The starting index from which to return the results.

Example Request

GET /v1/org/GB-GOR-DA1020/grants_made/?offset=100

Example Response

{
  "count": 5511,
  "next": "https://api.threesixtygiving.org/api/v1/org/GB-GOR-DA1020/grants_made/?limit=100&offset=100",
  "previous": "https://api.threesixtygiving.org/api/v1/org/GB-GOR-DA1020/grants_made/?limit=100",
  "results": [
    {
      "data": {
        "id": "360G-SCVO-a0V3z00000jlnvSEAQ",
        "title": "Maggie Keswick Jencks Cancer Caring Centres Trust",
        "currency": "GBP",
        "awardDate": "2021-01-06",
        "dataSource": "https://scvo.scot/funding/data/archive/communities-recovery-fund.json",
        "description": "Detailed description not provided.",
        "dateModified": "2021-05-31T15:24:54+00:00",
        "fromOpenCall": "Yes",
        "plannedDates": [
          {
            "dateModified": "2021-05-31T15:24:54+00:00"
          }
        ],
        "amountAwarded": 44560,
        "grantProgramme": [
          {
            "url": "https://scvo.scot/support/coronavirus/funding/scottish-government/community-recovery/crf",
            "code": "sg-crf-call-1",
            "title": "Communities Recovery Fund - Call 1",
            "description": "The Communities Recovery Fund, part of the Communities Recovery Programme and the Scottish Government’s £350m emergency response to coronavirus, is focused on providing funding to organisations that can support people who are facing additional barriers or have increased requirements as a direct result of the coronavirus (COVID19) pandemic."
          }
        ],
        "amountDisbursed": 28486,
        "classifications": [
          {
            "code": "category",
            "title": "Coronavirus (COVID-19)",
            "vocabulary": "Category",
            "description": "Providing funding to organisations as a direct result of the coronavirus (COVID-19) pandemic."
          }
        ],
        "amountAppliedFor": 28486,
        "fundingOrganization": [
          {
            "id": "GB-GOR-DA1020",
            "url": "https://gov.scot",
            "name": "Scottish Government"
          }
        ],
        "recipientOrganization": [
          {
            "id": "GB-SC-SC024414",
            "url": "https://www.maggies.org",
            "name": "Maggie Keswick Jencks Cancer Caring Centres Trust",
            "postalCode": "G11 6PA",
            "charityNumber": "SC024414",
            "streetAddress": "10 Dumbarton Road",
            "addressCountry": "Scotland",
            "addressLocality": "Glasgow"
          }
        ]
      },
      "publisher": {
        "self": "https://api.threesixtygiving.org/api/v1/org/GB-SC-SC003558/",
        "org_id": "GB-SC-SC003558"
      },
      "recipients": [
        {
          "self": "https://api.threesixtygiving.org/api/v1/org/GB-SC-SC024414/",
          "org_id": "GB-SC-SC024414"
        }
      ],
      "funders": [
        {
          "self": "https://api.threesixtygiving.org/api/v1/org/GB-GOR-DA1020/",
          "org_id": "GB-GOR-DA1020"
        }
      ],
      "grant_id": "360G-SCVO-a0V3z00000jlnvSEAQ"
    }
  ]
}

Grants Received by an Organisation

The Grants Received endpoint returns a paginated list of all known grants received by the given recipient organisation.

/v1/org/<org_id>/grants_received/

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Number of results to return per page. Maximum 1000.
`offset`	integer	No	The starting index from which to return the results.

Example Request

GET  /v1/org/GB-CHC-1164883/grants_received/?limit=10&offset=10

Example Response

{
"count": 28,
"next": "https://api.threesixtygiving.org/api/v1/org/GB-CHC-1164883/grants_received/?limit=10&offset=20",
"previous": "https://api.threesixtygiving.org/api/v1/org/GB-CHC-1164883/grants_received/?limit=10",
"results": [
{
"data": {
"id": "360G-indigotrust-IND419",
"title": "Supporting UK organisations to publish their grants data",
"currency": "GBP",
"awardDate": "2018-03-08",
"description": "Core funding.",
"dateModified": "2020-05-17T04:23:13Z",
"plannedDates": [
{
"endDate": "2019-03-08",
"duration": 12,
"startDate": "2018-03-08"
}
],
"amountAwarded": 30000,
"beneficiaryLocation": [
{
"name": "UK",
"countryCode": "GB"
}
],
"fundingOrganization": [
{
"id": "GB-CHC-1075920",
"name": "Indigo Trust"
}
],
"recipientOrganization": [
{
"id": "GB-CHC-1164883",
"name": "360 Giving",
"postalCode": "N1 9AG",
"addressRegion": "London",
"charityNumber": "GB-CHC-1164883",
"addressCountry": "UK"
}
]
},
"publisher": {
"self": "https://api.threesixtygiving.org/api/v1/org/GB-CHC-1075920/",
"org_id": "GB-CHC-1075920"
},
"recipients": [
{
"self": "https://api.threesixtygiving.org/api/v1/org/GB-CHC-1164883/",
"org_id": "GB-CHC-1164883"
}
],
"funders": [
{
"self": "https://api.threesixtygiving.org/api/v1/org/GB-CHC-1075920/",
"org_id": "GB-CHC-1075920"
}
],
"grant_id": "360G-indigotrust-IND419"
},
...
]
}

Schema & Interactive Docs

For more detail on the schema of responses, and an interactive way to try out the API in your browser, visit the API’s Swagger UI.

Support & Feedback

If you have any questions or suggestions about what the API can provide or do for you that aren’t answered by this documentation, please contact our free and friendly support helpdesk at labs@threesixtygiving.org, or post in our community forum under the API category.

Examples

Fetching all Grants Given to a Charity

An example using the Python requests library to fetch all the grants given to an organisation by charity number.

This example script is self-contained and can be run as-is, assuming the requests library is installed.

import time
import requests

# The base URL of the 360 Giving API
API_URL = "https://api.threesixtygiving.org/api/v1/"




def fetch_grants(charity_number):
# List of grants to be added to
grants = []

# The API expects organisations to be identified by Org Id (See: https://org-id.guide/about).
# Convert an England & Wales charity number into an Org Id by adding the "GB-CHC" prefix.
# For more info see: https://org-id.guide/list/GB-CHC
# and for charities in other parts of the UK: https://org-id.guide/results?structure=charity&coverage=GB&sector=all
org_id = "GB-CHC-" + charity_number

# Construct the starting URL for grants received by the charity
url = API_URL + "org/" + org_id + "/grants_received/"

# Note that the results are paginated, it may be necessary to fetch multiple pages.
# Loop until all pages are fetched.
while url is not None:
# Fetch the first page, and set the Accept header to get a JSON response
r = requests.get(url, headers={"Accept": "application/json"})

# Check for any HTTP error codes
r.raise_for_status()

# Convert the JSON response into a dict
data = r.json()

# For each page, add the page's results to our list of grants
grants.extend(
data["results"]
)

# And then fetch the next page
url = data["next"]

# Wait at least half a second between requests to not go over the usage limit
time.sleep(0.6)

return grants




if __name__ == "__main__":
# As an example, fetch grants given to England and Wales charity no. 221124
grants = fetch_grants(charity_number="221124")

# Print the grant title and funding organisation name for each grant
for grant in grants:
print(grant["data"]["title"] + " from " + grant["data"]["fundingOrganization"][0]["name"])