|
|
|
The Projects List API can be used to fetch a list of ClimateScan projects. Authorization for this endpoint is required. The Endpoint accepts API Key authorization and User Login authorization.
|
|
|
|
|
|
|
|
| Attribute | Value |
|
|
|
|
| --- | --- |
|
|
|
|
| URL | https://www.climatescan.org/api/v1/projects |
|
|
|
|
| Supported methods | `GET` |
|
|
|
|
| Authorization required | Yes - API key or User Login |
|
|
|
|
| Response type | JSON |
|
|
|
|
|
|
|
|
## Request
|
|
|
|
|
|
|
|
The Projects List API is idempotent and therefor only accepts the GET method.
|
|
|
|
|
|
|
|
The following query parameters are accepted to filter the list of projects. Please note that some parameters can only be used if you are authenticating with an API key.
|
|
|
|
|
|
|
|
| Query param | Type | Description | Example value |
|
|
|
|
| ----------- | --------- | ------------------------- | ------------- |
|
|
|
|
| `user_id` | `int` | Provide a User ID in order to return projects that were created by the specified user. This query param can only be used when authenticating with an API key. If you are authenticating as a user, then this query param will automatically be set to the authenticating user ID. | `1337` |
|
|
|
|
|
|
|
|
For example, if you are using an API key and want to filter projects created by user `1337`.
|
|
|
|
|
|
|
|
```
|
|
|
|
GET https://www.climatescan.org/api/v1/projects?user_id=1337
|
|
|
|
Authorization: ApiKey abc
|
|
|
|
```
|
|
|
|
|
|
|
|
In JavaScript, the request would look as follows.
|
|
|
|
|
|
|
|
```javascript
|
|
|
|
fetch('https://www.climatescan.org/api/v1/projects?user_id=1337', {
|
|
|
|
headers: {
|
|
|
|
Authorization: 'ApiKey abc',
|
|
|
|
}
|
|
|
|
})
|
|
|
|
.then(res => res.json());
|
|
|
|
```
|
|
|
|
|
|
|
|
For example, if you are authenticating through a Username and Password combination, the following will return a list of the user's projects:
|
|
|
|
|
|
|
|
```
|
|
|
|
GET https://www.climatescan.org/api/v1/projects
|
|
|
|
Authorization: Basic ZGVtbzpwQDU1dzByZA==
|
|
|
|
```
|
|
|
|
|
|
|
|
In JavaScript, the request would look as follows.
|
|
|
|
|
|
|
|
```javascript
|
|
|
|
fetch('https://www.climatescan.org/api/v1/projects', {
|
|
|
|
headers: {
|
|
|
|
Authorization: 'Basic ZGVtbzpwQDU1dzByZA==',
|
|
|
|
}
|
|
|
|
})
|
|
|
|
.then(res => res.json());
|
|
|
|
```
|
|
|
|
|
|
|
|
## Response
|
|
|
|
|
|
|
|
The Projects List API will always return a JSON-encoded list of **all projects** that match the given filter. You will have to implement pagination yourself.
|
|
|
|
|
|
|
|
Each entry in the response body is structured as follows.
|
|
|
|
|
|
|
|
| Attribute | Type | Description | Example value |
|
|
|
|
| --------- | ---- | ----------- | ------------- |
|
|
|
|
| `id` | `int` | ID of the project. | `"1128"` |
|
|
|
|
| `latitude` | `Decimal` | Latitude of the project location. | `53.1886` |
|
|
|
|
| `longitude` | `Decimal` | Longitude of the project location. | `6.95661` |
|
|
|
|
| `title` | `str` | Title of the project. | `"Groen dak ziekenhuis Ommelander"` |
|
|
|
|
| `categories` | `Category[]` | A list of categories this project was assigned to. Please refer to the table below for more information. | N/A |
|
|
|
|
| `url` | `str` | URL to the public project detail page. | `"https://www.climatescan.org/projects/1128/detail"` |
|
|
|
|
|
|
|
|
Example response:
|
|
|
|
|
|
|
|
```json
|
|
|
|
HTTP/2 200
|
|
|
|
Content-Type: application/json
|
|
|
|
|
|
|
|
[
|
|
|
|
{
|
|
|
|
"id": "6186",
|
|
|
|
"latitude": 52.4844,
|
|
|
|
"longitude": 11.5039,
|
|
|
|
"title": "Awesome project",
|
|
|
|
"categories": [
|
|
|
|
{
|
|
|
|
"id": 1,
|
|
|
|
"name": "(bio) swale",
|
|
|
|
"focustopic_id": 1,
|
|
|
|
"focustopic_name": "Water"
|
|
|
|
}
|
|
|
|
],
|
|
|
|
"url": "https://www.climatescan.org/projects/6186/detail"
|
|
|
|
},
|
|
|
|
...
|
|
|
|
]
|
|
|
|
```
|
|
|
|
|
|
|
|
### `Category` type
|
|
|
|
|
|
|
|
| Attribute | Type | Description | Example value |
|
|
|
|
| --------- | ---- | ----------- | ------------- |
|
|
|
|
| `id` | `int` | ID of the category. | `1` |
|
|
|
|
| `name` | `str` | Friendly name of the category. | `"(bio) swale"` |
|
|
|
|
| `focustopic_id` | `int` | Each category is assigned to a Focus Topic. This field refers to the ID of the parent Focus Topic. | `1` |
|
|
|
|
| `focustopic_name` | `str` | Each category is assigned to a Focus Topic. This field refers to the friendly name of the parent Focus Topic. | `"Water"` |
|
|
|
|
|
|
|
|
## Notes
|
|
|
|
|
|
|
|
* Please note that there is no limit to the amount of projects returned by this API. You will have to implement pagination in your frontend.
|
|
|
|
* Please note that you cannot filter projects based on User ID if you are authenticating as a User. The endpoint will automatically filter the list of projects based on the authenticated User ID. Please request an Application API key if you want to be able to fetch a full list of projects, or want to be able to filter on arbitrary User IDs. |
|
|
\ No newline at end of file |
