API technical documentation¶
This page goes into the technical documentation of our API.
The Lizard REST API is used to interact with Lizard data and objects. The API enables to collect, export and manage data. With the API, objects and data can be listed, created, (partially) updated and retrieved. Objects and data have different endpoints, to allow specific interactions.
The endpoints are browseable through the API root view:
Resources are addressable via an URL and can be interacted with via HTTP verbs. The most commonly used and supported verbs are:
- GET : retrieve data
- PUT : change data
- DELETE : delete data
- POST : add data
We also have HEAD and OPTIONS.
When you login via your browser, you get a session-based authentication token that is valid for 24 hours. All subsequent requests to the API are authenticated with that token.
Authenticating to the REST API outside of a browser is done by sending
password HTTP header fields with every request.
GET https://demo.lizard.net/api/v3/locations HTTP/1.1 Host: demo.lizard.net username: janedoe password: janespw
For all endpoints, users have to be
admin in the organisation that owns the
data to create or update resources.
See User management for more information about roles and permissions.
Supported data formats¶
The data formats supported depend on the endpoint, although JSON is generally available. See documentation on the individual endpoints for specifics.
The format of responses can be controlled by specifying an
in requests, e.g. Accept: application/json. When posting data, the
format of the payload must be specified via a
Content-Type header, e.g.
When interacting with the API via a browser, the
format query parameter
may also be used for controlling the format of the response, for example:
In this section, query parameters and response fields applicable to all endpoints are described.
The API supports the following common query parameters on GET list requests:
- page – offset number; default is 0.
- page_size – limit number of entries returned; default is 10.
All list responses share the following fields.
- count: number of results for this page
- next: url to next page, null if last page
- previous: url previous page, null if first page
- results: array with actual results
These fields are not specifically mentioned in the response description of each endpoint.
This section describes how the search endpoint can be used.
GET https://demo.lizard.net/api/v3/search/?q=water GET https://demo.lizard.net/api/v3/search/?type=assetgroup,eventseries GET https://demo.lizard.net/api/v3/search/?exclude=ef34gh3 GET https://demo.lizard.net/api/v3/search/?q=water&in_bbox=4.6,52.1,5.2,52.5&srid=4326 GET https://demo.lizard.net/api/v3/search/?q=water&point=POINT (5 53)&dist=10000
This API endpoint supports the following parameters on GET requests:
- q – Full-text search filter limited to: bridges, culverts, groundwater stations, levees, levee cross sections, measuring stations, monitoring wells, pressure pipes, pump stations, sluices, waste water treatment plants, and weirs. A search query filter should at least contain two characters.
- in_bbx – comma-separated string of a bounding-box, of the form: “xmin,ymin,xmax,ymax”.
- dist – Distance in meters.
- point – Point geometry (either WKT or GeoJSON).
- srid – Spatial Reference System Identifier.
- type – Comma-seperated list of entity types. Currently the only way to search for layer metadata is by explicitly requesting those entities: type=rasterstore,scenario,assetlayer. It may also be used to limit search results to specific types, i.e. type=levees.
- exclude – Comma-seperated list of exclude terms. Results are excluded if the url of the resource contains a term. This is done in the viewset so the serializer still respects the requested page_size.
This section describes timeseries-related endpoints.
This section describes location-related endpoints.