Filtering data in endpoints
The endpoints are designed to provide a easy interface to a complex data. Its possible to get information about users, projects, licenses, categories or advanced pre-calculated reports.
A common set of filters may be available trough all the endpoints with slightly different meanings depending on the context.
Some endpoints may have a reduced set of filters or have a bigger one. Check documentation for each of them.
Apply any filter by sending it in the request's query string
GET https://api.goteo.org/v1/users/?node=barcelona HTTP/1.1
COMMON FILTERS:
| Parameter | Type | Description |
|---|---|---|
| page | number | Some endpoints are paginated, by appending ?page= to the request you will obtain the specified page in the response. This parameter is zero-based, number 0 is the first page, 1 is the second and so on... |
| limit | number | Also for the paginated endpoints you can specify the maximum number of items per page. The maximum items per page allowed is 50. |
| lang | string (*multiple) | Some endpoints returns may return content in different languages. This parameter allows to specify one or two languages (ISO 639-1 code) for the displayed content. Note that not all content are available in all languages. Missing content will be displayed in the second specified language (if available) or in the platform default. Currently, these languages are available: es (Spanish, default), en (English), ca (Catalan), eu (Basque) gl (Galician), it (Italy), nl (Dutch) |
| project | string (*multiple) | Providing a project-id here will restrict the results to the specified projects. |
| category | number (*multiple) | Same as before, you can restrict the results to the specified categories. Note that the value expected here is the id of the category. You can obtain this id from the categories endpoint. |
| social_commitment | number (*multiple) | Like categories, you can restrict the results to the specified social commitments. Note that the value expected here is the id of the social_commitment. You can obtain this id from the social commitments endpoint. |
| sdg | number (*multiple) | Sustainable Development Goals can also be used to restrict the results. Note that the value expected here is the id of the sdg. You can obtain this id from the SDGs endpoint. |
| footprint | number (*multiple) | Footprints is a meta-categorization scope, you can restrict results by this value too. Note that the value expected here is the id of the footprint. You can obtain this id from the footprints endpoint. |
| node | string (*multiple) | This allows you to restrict the results to a single node (known as channel as well) of Goteo. Currently, we don't have and endpoint for channels (yet), check out the active ones in the official website: goteo.org/channels, to exclude channels results use goteo as the general node |
| call | string (*multiple) | This allows you to restrict the results to a single matchfunding call. Check for existing calls in Calls |
| matcher | string (*multiple) | This allows you to restrict the results to a single matchfunding matcher. Check for existing matchers in Matchers |
| from_date | date | Results can be confined into a range of dates, use this parameter to specify the start date you want results for. The date expected format is YYYY-MM-DD |
| to_date | date | Same as from_date, sets the last date you want results for. |
| location | numbers (csv) | This parameter allows you to restrict results to a certain geographic point and a radius around it. The point coordinates must be in decimal degrees (latitude, longitude) and the radius in Km (with a maximum of 500Km). All 3 values must separated by a comma(,): longitude,latitude,radius For instance: ?location=41.38879,2.15899,100 will return results around the city of Barcelona in a radius of 100Km. |
*multiple: These parameters can be queried multiple times and all values will be included in the filter.
For instance:
?node=barcelona&node=euskadi appended to the request will return all the items related to this 2 nodes (barcelona and euskadi).
?lang=eu&lang=en appended to the request will return the results localized in Basque language, English if Basque is not available or, finally, in the default language (Spanish) if none of them matches.
Examples:
Obtaining a list of users created in Goteo around Barcelona in a radius of 50Km during the year 2014:
curl --basic --user "user:key" \
"https://api.goteo.org/v1/users/?location=41.38879,2.15899,50&from_date=2014-01-01&to_date=2014-12-31"
Obtaining all the money statistics for the project a single project:
curl --basic --user "user:key" \
"https://api.goteo.org/v1/reports/money/?project=crowdfundparato"
Obtaining all the community reports for the nodes of barcelona, euskadi an andalucia together:
curl --basic --user "user:key" \
"https://api.goteo.org/v1/reports/community/?node=barcelona&node=euskadi&node=andalucia"