World Cleanup REST API

Base URL: https://api-qa.app.worldcleanupday.com/api/v1, Version: 1.0

Default request content-types: application/json
Default response content-types: application/json, text/html, text/plain
Schemes: http, https

Summary

Path Operation Description
/admin/trashpoints GET
/areas GET
/areas/user GET
/areas/user/{id} GET
/areas/{id}/leader DELETE
/areas/{id}/leader/{id2} PUT
/areas/{id}/trashpoints GET
/auth DELETE
/auth/external POST
/datasets GET
/me GET
PUT
/me/accept-terms PUT
/overview/clusters POST
/overview/trashpoints POST
/overview/trashpoints/grid POST
/trashpoints PUT
/trashpoints/user GET
/trashpoints/{id} DELETE
GET
PUT
/trashpoints/{id}/images GET
POST
PUT
/trashpoints/{id}/images/{id2} DELETE
/users GET
/users/{id} GET
/users/{id}/lock PUT

Paths

GET /admin/trashpoints

Fetch location trashpoints contained in a specific dataset, within a specific polygon, and for a certain zoom level.
pageSize

number of items on a page.

 query integer , { x ∈ ℤ | 10 ≤ x ≤ 50 } #/parameters/PageSize
pageNumber

number of items on a page.

 query integer , { x ∈ ℤ | x ≥ 1 } #/parameters/PageNumber

Uses default content-types: application/json text/html text/plain

200 OK #/responses/AdminTrashpoints

List of trashpoints for admin consumption.

PaginatedTrashpoints
default #/responses/ErrorSet

Contains errors.

Error

GET /areas

List all areas.
parentId

Use if only areas with a specific parent should be returned.

 query string

Uses default content-types: application/json text/html text/plain

200 OK

List of areas.

Area
default #/responses/ErrorSet

Contains errors.

Error

GET /areas/user

List areas assigned to the account of the currently logged-in user.

Uses default content-types: application/json text/html text/plain

200 OK

List of areas.

Area
default #/responses/ErrorSet

Contains errors.

Error

GET /areas/user/{id}

List areas assigned to a specific user.
id

UUID.

 path string #/parameters/UUID

Uses default content-types: application/json text/html text/plain

200 OK

List of areas.

Area
default #/responses/ErrorSet

Contains errors.

Error

DELETE /areas/{id}/leader

Remove the leader of an area.
id

UUID.

 path string #/parameters/UUID

Uses default content-types: application/json text/html text/plain

200 OK

User was successfully unassigned from area.

default #/responses/ErrorSet

Contains errors.

Error

PUT /areas/{id}/leader/{id2}

Assign an user as leader of an area.
id

UUID.

 path string #/parameters/UUID
id2

UUID.

 path string #/parameters/UUID2

Uses default content-types: application/json text/html text/plain

200 OK

User was successfully assigned to area.

default #/responses/ErrorSet

Contains errors.

Error

GET /areas/{id}/trashpoints

List of trashpoints falling into a specific area. Use special area code "-" (single dash) to request trashpoints which don't fall into any defined area.
id

UUID.

 path string #/parameters/UUID
pageSize

number of items on a page.

 query integer , { x ∈ ℤ | 10 ≤ x ≤ 50 } #/parameters/PageSize
pageNumber

number of items on a page.

 query integer , { x ∈ ℤ | x ≥ 1 } #/parameters/PageNumber

Uses default content-types: application/json text/html text/plain

200 OK #/responses/AreaTrashpoints

List of trashpoints for area leader consumption.

PaginatedAreaTrashpoints
default #/responses/ErrorSet

Contains errors.

Error

DELETE /auth

End the user's session.

Uses default content-types: application/json text/html text/plain

200 OK

User was logged out.

default #/responses/ErrorSet

Contains errors.

Error

POST /auth/external

Obtain an authorization token in exchange for an OAUTH token from another authority.
credentials

Credentials used for authorization.

 body object #/parameters/AuthRequest

Uses default content-types: application/json text/html text/plain

200 OK

Contains authorization data.

AuthPermission
default #/responses/ErrorSet

Contains errors.

Error

GET /datasets

Fetch information about all the datasets offered by this server.

Uses default content-types: application/json text/html text/plain

200 OK

List of datasets.

Dataset
default #/responses/ErrorSet

Contains errors.

Error

GET /me

Information about the currently logged-in user.

Uses default content-types: application/json text/html text/plain

200 OK

Account information.

AccountPlusAreas
default #/responses/ErrorSet

Contains errors.

Error

PUT /me

Change details about the user.
update body object #/parameters/ModifyProfile

Uses default content-types: application/json text/html text/plain

200 OK

Account information.

Account
default #/responses/ErrorSet

Contains errors.

Error

PUT /me/accept-terms

Mark the terms and conditions accepted for the logged-in user account.

Uses default content-types: application/json text/html text/plain

200 OK

The terms were marked accepted on this account.

default #/responses/ErrorSet

Contains errors.

Error

POST /overview/clusters

Fetch clustered trashpoints from a specific dataset, within a certain rectangular area, and for a certain grid scale.
query body object #/parameters/MapQuery

Uses default content-types: application/json text/html text/plain

200 OK

List of clusters.

Cluster
default #/responses/ErrorSet

Contains errors.

Error

POST /overview/trashpoints

Fetch isolated (ie. with no neighbors nearby) location trashpoints from a specific dataset, within a certain rectangular area, and for a certain grid scale.
query body object #/parameters/MapQuery

Uses default content-types: application/json text/html text/plain

200 OK

List of simplified trashpoint data.

OverviewTrashpoint
default #/responses/ErrorSet

Contains errors.

Error

POST /overview/trashpoints/grid

Fetch isolated (ie. with no neighbors nearby) location trashpoints from a specific dataset, within a certain grid slot, for a certain grid scale.
query body object #/parameters/MapQueryGrid

Uses default content-types: application/json text/html text/plain

200 OK

List of simplified trashpoint data.

OverviewTrashpoint
default #/responses/ErrorSet

Contains errors.

Error

PUT /trashpoints

Create a new trashpoint in a certain dataset ID.
trashpoint body object #/parameters/CreateTrashpoint

Uses default content-types: application/json text/html text/plain

200 OK

The newly created trashpoint.

Trashpoint
default #/responses/ErrorSet

Contains errors.

Error

GET /trashpoints/user

Fetch full information about trashpoints associated to the authenticated user.
pageSize

number of items on a page.

 query integer , { x ∈ ℤ | 10 ≤ x ≤ 50 } #/parameters/PageSize
pageNumber

number of items on a page.

 query integer , { x ∈ ℤ | x ≥ 1 } #/parameters/PageNumber

Uses default content-types: application/json text/html text/plain

200 OK #/responses/AdminTrashpoints

List of trashpoints for admin consumption.

PaginatedTrashpoints
default #/responses/ErrorSet

Contains errors.

Error

DELETE /trashpoints/{id}

Remove a specific trashpoint.
id

UUID.

 path string #/parameters/UUID

Uses default content-types: application/json text/html text/plain

200 OK

Trashpoint has been removed.

default #/responses/ErrorSet

Contains errors.

Error

GET /trashpoints/{id}

Fetch full information about a specific trashpoint ID.
id

UUID.

 path string #/parameters/UUID

Uses default content-types: application/json text/html text/plain

200 OK

Individual trashpoint or cluster.

Trashpoint
default #/responses/ErrorSet

Contains errors.

Error

PUT /trashpoints/{id}

Modify details of a specific trashpoint.
id

UUID.

 path string #/parameters/UUID
trashpoint body object #/parameters/ModifyTrashpoint

Uses default content-types: application/json text/html text/plain

200 OK

Individual trashpoint or cluster.

Trashpoint
default #/responses/ErrorSet

Contains errors.

Error

GET /trashpoints/{id}/images

Fetch the images associated with a specific trashpoint ID.
id

UUID.

 path string #/parameters/UUID

Uses default content-types: application/json text/html text/plain

200 OK

List of images.

TrashpointImage
default #/responses/ErrorSet

Contains errors.

Error

POST /trashpoints/{id}/images

Confirm the upload of an image.
id

UUID.

 path string #/parameters/UUID
request body object #/parameters/ImageConfirm

Uses default content-types: application/json text/html text/plain

200 OK

All indicated images were processed successfully.

default #/responses/ErrorSet

Contains errors.

Error

PUT /trashpoints/{id}/images

Allocate a new image associated with a specific trashpoint ID.
id

UUID.

 path string #/parameters/UUID
request body object #/parameters/ImageAllocate

Uses default content-types: application/json text/html text/plain

200 OK #/responses/StorageAuth

A short-term authorization allowing access to storage operations.

object
permission: AuthPermission
type: TrashImageType

The type of resource.

default #/responses/ErrorSet

Contains errors.

Error

DELETE /trashpoints/{id}/images/{id2}

Delete an image. The 1st ID indicates the trashpoint, the 2nd the image.
id

UUID.

 path string #/parameters/UUID
id2

UUID.

 path string #/parameters/UUID2

Uses default content-types: application/json text/html text/plain

200 OK

The indicated image and their dependent images were deleted.

default #/responses/ErrorSet

Contains errors.

Error

GET /users

Fetch all users.
pageSize

number of items on a page.

 query integer , { x ∈ ℤ | 10 ≤ x ≤ 50 } #/parameters/PageSize
pageNumber

number of items on a page.

 query integer , { x ∈ ℤ | x ≥ 1 } #/parameters/PageNumber
country query string , x ∈ { AD , AE , AF , AG , AI , AL , AM , AO , AQ , AR , AS , AT , AU , AW , AX , AZ , BA , BB , BD , BE , BF , BG , BH , BI , BJ , BL , BM , BN , BO , BQ , BR , BS , BT , BV , BW , BY , BZ , CA , CC , CD , CF , CG , CH , CI , CK , CL , CM , CN , CO , CR , CU , CV , CW , CX , CY , CZ , DE , DJ , DK , DM , DO , DZ , EC , EE , EG , EH , ER , ES , ET , FI , FJ , FK , FM , FO , FR , GA , GB , GD , GE , GF , GG , GH , GI , GL , GM , GN , GP , GQ , GR , GS , GT , GU , GW , GY , HK , HM , HN , HR , HT , HU , ID , IE , IL , IM , IN , IO , IQ , IR , IS , IT , JE , JM , JO , JP , KE , KG , KH , KI , KM , KN , KP , KR , KW , KY , KZ , LA , LB , LC , LI , LK , LR , LS , LT , LU , LV , LY , MA , MC , MD , ME , MF , MG , MH , MK , ML , MM , MN , MO , MP , MQ , MR , MS , MT , MU , MV , MW , MX , MY , MZ , NA , NC , NE , NF , NG , NI , NL , NO , NP , NR , NU , NZ , OM , PA , PE , PF , PG , PH , PK , PL , PM , PN , PR , PS , PT , PW , PY , QA , RE , RO , RS , RU , RW , SA , SB , SC , SD , SE , SG , SH , SI , SJ , SK , SL , SM , SN , SO , SR , SS , ST , SV , SX , SY , SZ , TC , TD , TF , TG , TH , TJ , TK , TL , TM , TN , TO , TR , TT , TV , TZ , UA , UG , UM , US , UY , UZ , VA , VC , VE , VG , VI , VN , VU , WF , WS , YE , YT , ZA , ZM , ZW } #/parameters/Country

Uses default content-types: application/json text/html text/plain

200 OK

List of accounts.

total: PageTotal
pageSize: PageSize
pageNumber: PageNumber
records: object[]
Account
default #/responses/ErrorSet

Contains errors.

Error

GET /users/{id}

Fetch complete info about a specific user.
id

UUID.

 path string #/parameters/UUID

Uses default content-types: application/json text/html text/plain

200 OK

Full account information.

AccountFullInfo
default #/responses/ErrorSet

Contains errors.

Error

PUT /users/{id}/lock

Set lock status on an account.

Uses default content-types: application/json

locked: boolean

True if the account should be locked, false if it should be unlocked.
id

UUID.

 path string #/parameters/UUID

Uses default content-types: application/json text/html text/plain

200 OK

The user account was locked or unlocked successfully.

default #/responses/ErrorSet

Contains errors.

Error

Parameter definitions
PageSize pageSize

number of items on a page.

 query integer , { x ∈ ℤ | 10 ≤ x ≤ 50 }
PageNumber pageNumber

number of items on a page.

 query integer , { x ∈ ℤ | x ≥ 1 }
ImageAllocate request body object
ImageConfirm request body object
Country country query string , x ∈ { AD , AE , AF , AG , AI , AL , AM , AO , AQ , AR , AS , AT , AU , AW , AX , AZ , BA , BB , BD , BE , BF , BG , BH , BI , BJ , BL , BM , BN , BO , BQ , BR , BS , BT , BV , BW , BY , BZ , CA , CC , CD , CF , CG , CH , CI , CK , CL , CM , CN , CO , CR , CU , CV , CW , CX , CY , CZ , DE , DJ , DK , DM , DO , DZ , EC , EE , EG , EH , ER , ES , ET , FI , FJ , FK , FM , FO , FR , GA , GB , GD , GE , GF , GG , GH , GI , GL , GM , GN , GP , GQ , GR , GS , GT , GU , GW , GY , HK , HM , HN , HR , HT , HU , ID , IE , IL , IM , IN , IO , IQ , IR , IS , IT , JE , JM , JO , JP , KE , KG , KH , KI , KM , KN , KP , KR , KW , KY , KZ , LA , LB , LC , LI , LK , LR , LS , LT , LU , LV , LY , MA , MC , MD , ME , MF , MG , MH , MK , ML , MM , MN , MO , MP , MQ , MR , MS , MT , MU , MV , MW , MX , MY , MZ , NA , NC , NE , NF , NG , NI , NL , NO , NP , NR , NU , NZ , OM , PA , PE , PF , PG , PH , PK , PL , PM , PN , PR , PS , PT , PW , PY , QA , RE , RO , RS , RU , RW , SA , SB , SC , SD , SE , SG , SH , SI , SJ , SK , SL , SM , SN , SO , SR , SS , ST , SV , SX , SY , SZ , TC , TD , TF , TG , TH , TJ , TK , TL , TM , TN , TO , TR , TT , TV , TZ , UA , UG , UM , US , UY , UZ , VA , VC , VE , VG , VI , VN , VU , WF , WS , YE , YT , ZA , ZM , ZW }
ModifyProfile update body object
ModifyTrashpoint trashpoint body object
CreateTrashpoint trashpoint body object
MapQuery query body object
MapQueryGrid query body object
UUID id

UUID.

 path string
UUID2 id2

UUID.

 path string
AuthRequest credentials

Credentials used for authorization.

 body object

Response definitions

AdminTrashpoints

List of trashpoints for admin consumption.

PaginatedTrashpoints
AreaTrashpoints

List of trashpoints for area leader consumption.

PaginatedAreaTrashpoints
StorageAuth

A short-term authorization allowing access to storage operations.

object
permission: AuthPermission
type: TrashImageType

The type of resource.

ErrorSet

Contains errors.

Error

Schema definitions

Account: object

id: UUID
name: string
email: string
role: string , x ∈ { volunteer , leader , admin , superadmin }
country: CountryCode
pictureURL: string
termsAcceptedAt: ISOTimestamp
locked: boolean

AccountFullInfo:

locked: boolean
createdAt: ISOTimestamp
createdBy: UUID
updatedAt: ISOTimestamp

When the account was last modified. If missing it means this is a freshly created account.

updatedBy: UUID

Who caused this account to be last modified. If missing it means this is a freshly created account.

AccountPlusAreas:

areas: string[]

Empty for users who are not area leaders. Contains area codes led by this user.

string (at least 2 chars)

Area: object

id: string

A unique code in geo HASC notation. Eg. US.CA.SF would mean US > California > San Francisco.

name: string
parentId: string

Each area can optionally be classified as physically located under another.

leaderId: UUID

Area can be optionally be assigned to a user.

AuthPermission: object

token: AuthToken
resourceId: UUID

AuthSource: string , x ∈ { facebook , google }

AuthToken: string

BriefTrashpoint:

Simplified version of trashpoint, used when listing a user's own trashpoints.

name: string

A unique name of this trashpoint.

address: string

The address where the trashpoint was created.

Cluster: object

If not present, this object is a trashpoint. If present, this object is a cluster and this property contains cluster-specific properties.

count: number (int32) , { x ∈ ℝ | x ≥ 1 }
status: TrashStatus
location: GeoPoint
coordinates: GridCoordinates

Count: number (int32) , { x ∈ ℝ | x ≥ 0 }

A count of some sort.

CountryCode: string , x ∈ { AD , AE , AF , AG , AI , AL , AM , AO , AQ , AR , AS , AT , AU , AW , AX , AZ , BA , BB , BD , BE , BF , BG , BH , BI , BJ , BL , BM , BN , BO , BQ , BR , BS , BT , BV , BW , BY , BZ , CA , CC , CD , CF , CG , CH , CI , CK , CL , CM , CN , CO , CR , CU , CV , CW , CX , CY , CZ , DE , DJ , DK , DM , DO , DZ , EC , EE , EG , EH , ER , ES , ET , FI , FJ , FK , FM , FO , FR , GA , GB , GD , GE , GF , GG , GH , GI , GL , GM , GN , GP , GQ , GR , GS , GT , GU , GW , GY , HK , HM , HN , HR , HT , HU , ID , IE , IL , IM , IN , IO , IQ , IR , IS , IT , JE , JM , JO , JP , KE , KG , KH , KI , KM , KN , KP , KR , KW , KY , KZ , LA , LB , LC , LI , LK , LR , LS , LT , LU , LV , LY , MA , MC , MD , ME , MF , MG , MH , MK , ML , MM , MN , MO , MP , MQ , MR , MS , MT , MU , MV , MW , MX , MY , MZ , NA , NC , NE , NF , NG , NI , NL , NO , NP , NR , NU , NZ , OM , PA , PE , PF , PG , PH , PK , PL , PM , PN , PR , PS , PT , PW , PY , QA , RE , RO , RS , RU , RW , SA , SB , SC , SD , SE , SG , SH , SI , SJ , SK , SL , SM , SN , SO , SR , SS , ST , SV , SX , SY , SZ , TC , TD , TF , TG , TH , TJ , TK , TL , TM , TN , TO , TR , TT , TV , TZ , UA , UG , UM , US , UY , UZ , VA , VC , VE , VG , VI , VN , VU , WF , WS , YE , YT , ZA , ZM , ZW }

ISO ALPHA-2 country code.

Dataset: object

A collection of data objects with a common internal structure.

id: UUID
type: string , x ∈ { trashpoints }

The type of objects contained in this dataset.

Error: object

code: string
message: string

GeoLatitude: number (float) , { x ∈ ℝ | -90 ≤ x ≤ 90 }

Geographical geodetic latitude, expressed in decimal degrees in the range (-90, 90).

GeoLongitude: number (float) , { x ∈ ℝ | -180 ≤ x ≤ 180 }

Geographical geodetic longitude, expressed in decimal degrees in the range (-180, 180).

GeoPoint: object

A geographical point coordinate, expressed as latitude and longitude.

latitude: GeoLatitude
longitude: GeoLongitude

GeoRectangle: object

Two geopoints that represent the corners of a rectangle.

nw: GeoPoint
se: GeoPoint

GeoScale: string , x ∈ { 1000km , 500km , 300km , 200km , 180km , 160km , 140km , 120km , 100km , 90km , 80km , 70km , 60km , 50km , 30km , 20km , 10km , 5km , 3km , 2km , 1km , 500m , 300m , 200m , 100m , 50m , 30m , 20m , 10m , 5m , 1m }

GridCoordinates: number[]

A set of integer representing the coordinates of a cluster grid cell.

number (int32)

ISOTimestamp: string , must match ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$

ISO8601 timestamp.

OverviewTrashpoint: object

Simplified version of trashpoint, used when listing trashpoint overviews.

id: UUID
location: GeoPoint
status: TrashStatus

PageNumber: integer , { x ∈ ℤ | x ≥ 1 }

The number of the page requested regarding pagination.

PageSize: integer , { x ∈ ℤ | 10 ≤ x ≤ 50 }

The number of trashpoints returned.

PageTotal: integer , { x ∈ ℤ | x ≥ 0 }

Total number of user's trashpoints.

PaginatedAreaTrashpoints:

statusCounts: object
threat: Count
regular: Count
cleaned: Count
outdated: Count

PaginatedTrashpoints: object

total: PageTotal
pageSize: PageSize
pageNumber: PageNumber
records: object[]
BriefTrashpoint

TrashAddress: string (1 to 250 chars)

TrashAmount: string , x ∈ { handful , bagful , cartload , truckload }

The amount of trash.

TrashAreas: string[]

Under what geographical areas this trashpoint falls.

string (at least 1 chars)

TrashComposition: string[]

The type of composition the trash is made of.

string , x ∈ { glass , electronics , paper , domestic waste , furniture , organic waste , plastic , metal , tyres }

TrashCreateStatus: string , x ∈ { threat , regular }

The initial status of a newly created trashpoint.

TrashHashtags: string[]

Extra information added by the user describing the trash.

string (2 to 26 chars) , must match ^#[a-zA-Z0-9]+$

1-25 characters plus leading hash (#).

TrashImageType: string , x ∈ { medium , thumbnail }

TrashModifyStatus: string , x ∈ { threat , regular , cleaned }

Change the status of the trashpoint.

TrashName: string (1 to 100 chars)

Trashpoint:

Full version of a trashpoint.

composition: TrashComposition
amount: TrashAmount
hashtags: TrashHashtags
counter: integer , { x ∈ ℤ | x ≥ 1 }
createdAt: ISOTimestamp
updatedAt: ISOTimestamp
createdBy: UUID
updatedBy: UUID
createdByName: string

Name of the user that created this trashpoint.

updatedByName: string

Name of the user that updated this trashpoint.

areas: TrashAreas

TrashpointImage: object

id: UUID

The unique identifier for this image.

trashpointId: UUID

The identifier of the trashpoint this image is associated with.

type: TrashImageType
url: string

The URL at which the image is available. Not present when the status is not "ready".

parentId: UUID

Depending on the type, some images are related to another.

TrashStatus: string , x ∈ { threat , regular , cleaned , outdated }

The current status of this trashpoint. If it's a cluster, the status is determined by the majority of trashpoints in it.

UUID: string

UUID that serves to uniquely identify this object.