Using the API
Authentication
The 360Giving API provides read-only access to open datasets, and no authorisation is required to use it. All endpoints can be used without providing an authentication token.
Headers
The 360Giving API requires all requests to set the Accept header to application/JSON. This is shown in the Python and cURL examples. 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.guide 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.
360Giving data largely contains identifiers for charities, companies, government and research organisations in the UK. Here are some Org ID prefixes (schemes) commonly found in 360Giving 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
The Grants Made, Grants Received and Organisation List endpoints return a large number of results. 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 above 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. The results contain 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 book a 1-1 Data Support call 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 Org ID provided is not found in the 360Giving data. 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 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.
If you build an application using the 360Giving API, you should ensure that it handles these errors appropriately, e.g. by informing the user that an organisation was 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 360Giving 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, you must ensure that you take action promptly when we contact you about take down requests.
All API users should register for updates to be informed about 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. Register for important updates on any changes to the 360Giving API.
Testing
As the 360Giving 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.
Questions or suggestions for the API?
With this API, 360Giving aims to make it easier for people to build applications that consume 360Giving data. If you have any questions or suggestions about what the API can provide or do for you that aren’t answered in this documentation, please contact us.