SeagrassSpotter API
Last updated: November 14, 2024
SeagrassSpotter API
Introduction
This page aims to provide documentation required to retrieve some of the publicly accessible data from the SeagrassSpotter API.
This is not an exhastive list of all methods, but it will be updated over time as the API is opened up to the public.
The Spotter API uses JSON for all successful responses.
Any GET requests which can't be found (for example requesting an invalid sighting id) will result in a 404 HTTP status code, and the result "Unable to find the resource you're looking for"
Each endpoint contains code examples in different programming languages to the right (or as part of the content on mobile).
Authenticating requests
This API is not authenticated.
Absences
Get All Absences
GET
https://api.seagrassspotter.org
/v1/absence
Gets an array of all the absences.
Along with the raw absence data, it also includes basic information about the user who submitted it.
curl --request GET \
--get "https://api.seagrassspotter.org/v1/absence"[
{
"id": 5,
"created_at": "2023-06-07T03:03:47.000000Z",
"updated_at": "2023-06-07T03:03:47.000000Z",
"user_id": 19,
"photo_path": "/media/defaults/absence-blank.png",
"thumb_path": "/media/defaults/absence-blank.png",
"latitude": 51.456602,
"longitude": -3.147328,
"accuracy": 1000,
"date_spotted": "2023-06-07",
"mobile_upload": 0,
"sediment": 1,
"status": 0,
"habitat": 1,
"comments": null,
"country": "United Kingdom",
"country_code": "GB",
"country_area": "Cardiff",
"flagged": 0,
"admin_confirmed": 0,
"flagged_reason": null,
"user": {
"id": 19,
"username": "benjones",
"avatar": "/media/profile-images/1509976897361_13899.jpg"
}
},
{
"id": 7,
"created_at": "2023-06-08T10:40:36.000000Z",
"updated_at": "2023-06-08T10:40:36.000000Z",
"user_id": 3519,
"photo_path": "/media/absence/2023-06/1686238836700838709.jpg",
"thumb_path": "/media/absence/2023-06/1686238836700838709_thumbnail.jpg",
"latitude": 51.463893,
"longitude": -3.64369,
"accuracy": 1000,
"date_spotted": "2023-06-08",
"mobile_upload": 1,
"sediment": 2,
"status": 0,
"habitat": 1,
"comments": null,
"country": "United Kingdom",
"country_code": "GB",
"country_area": "Wales",
"flagged": 0,
"admin_confirmed": 0,
"flagged_reason": null,
"user": {
"id": 3519,
"username": "flot",
"avatar": "/media/defaults/avatar-blank.jpg"
}
},
{
"id": 9,
"created_at": "2023-06-15T01:28:26.000000Z",
"updated_at": "2023-06-15T01:28:26.000000Z",
"user_id": 2369,
"photo_path": "/media/absence/2023-06/1686810506212983829.jpg",
"thumb_path": "/media/absence/2023-06/1686810506212983829_thumbnail.jpg",
"latitude": 51.71529,
"longitude": 0.834907,
"accuracy": 1000,
"date_spotted": "2023-06-15",
"mobile_upload": 1,
"sediment": 7,
"status": 0,
"habitat": 4,
"comments": "Tiny patches of green algae approximately 2m away from seagrass",
"country": "United Kingdom",
"country_code": "GB",
"country_area": "Southminster",
"flagged": 0,
"admin_confirmed": 0,
"flagged_reason": null,
"user": {
"id": 2369,
"username": "drice98",
"avatar": "/media/defaults/avatar-blank.jpg"
}
}
]Get An Absence
GET
https://api.seagrassspotter.org
/v1/absence/{id}
Gets a single absence.
Along with the raw sighting data, it also includes basic information about the user who submitted it.
If you pass the optional nearby parameter, it will also include up to 3
random sightings from within a 20km range as an array under the nearby property.
URL Parameters
id
integer
The ID of the sighting
Example:
53
Query Parameters
nearby
boolean
Also include up to 3 nearby absences
Example:
1
curl --request GET \
--get "https://api.seagrassspotter.org/v1/absence/53?nearby=1"{
"id": 53,
"created_at": "2023-08-29T09:22:27.000000Z",
"updated_at": "2023-08-29T09:22:27.000000Z",
"user_id": 3862,
"photo_path": "/media/absence/2023-08/1693318947231328096.jpg",
"thumb_path": "/media/absence/2023-08/1693318947231328096_thumbnail.jpg",
"latitude": 28.895009,
"longitude": -82.593476,
"accuracy": 1000,
"date_spotted": "2023-08-29",
"mobile_upload": 1,
"sediment": 7,
"status": 0,
"habitat": 13,
"comments": "loads of Rockstar Eel Grass in abundance",
"country": "United States",
"country_code": "US",
"country_area": "Citrus County",
"flagged": 0,
"admin_confirmed": 0,
"flagged_reason": null,
"nearby": [],
"user": {
"id": 3862,
"username": "SNOAP",
"avatar": "/media/defaults/avatar-blank.jpg"
}
}Sightings
Get All Sightings
GET
https://api.seagrassspotter.org
/v1/sighting
Gets an array of all the sightings.
Along with the raw sighting data, it also includes basic information about the user who submitted it.
curl --request GET \
--get "https://api.seagrassspotter.org/v1/sighting"[
{
"id": 7379,
"created_at": "2023-09-02T00:51:15.000000Z",
"updated_at": "2023-09-02T00:51:15.000000Z",
"user_id": 1788,
"photo_path": "/media/sightings/2023-09/1693633874810989176.jpg",
"thumb_path": "/media/sightings/2023-09/1693633874810989176_thumbnail.jpg",
"latitude": 50.735672,
"longitude": -1.375021,
"accuracy": 1000,
"date_spotted": "2023-09-02",
"mobile_upload": 1,
"observe": 0,
"extensive": 0,
"length": 0,
"flowers": 0,
"sediment": 0,
"algae": 0,
"boats": 0,
"moorings": 0,
"intertidal": 0,
"damages": null,
"changes": null,
"additional_species": null,
"country": "United Kingdom",
"country_code": "GB",
"country_area": "Newport",
"fishing": 0,
"fishing_gear": null,
"fishing_caught": null,
"depth": 0,
"confidence": 3,
"flagged": 0,
"admin_confirmed": 0,
"flagged_reason": null,
"species": [
{
"id": 31,
"display_name": "Zostera marina"
}
],
"user": {
"id": 1788,
"username": "LauraMcC",
"avatar": "/media/defaults/avatar-blank.jpg"
}
},
{
"id": 7380,
"created_at": "2023-09-02T08:47:47.000000Z",
"updated_at": "2023-09-02T08:47:47.000000Z",
"user_id": 3793,
"photo_path": "/media/sightings/2023-09/1693662467370551701.jpg",
"thumb_path": "/media/sightings/2023-09/1693662467370551701_thumbnail.jpg",
"latitude": 50.103493,
"longitude": -5.111807,
"accuracy": 1000,
"date_spotted": "2023-09-02",
"mobile_upload": 1,
"observe": 1,
"extensive": 6,
"length": 4,
"flowers": 0,
"sediment": 2,
"algae": 0,
"boats": 4,
"moorings": 4,
"intertidal": 0,
"damages": null,
"changes": null,
"additional_species": null,
"country": "United Kingdom",
"country_code": "GB",
"country_area": "Falmouth",
"fishing": 0,
"fishing_gear": null,
"fishing_caught": null,
"depth": 1,
"confidence": 2,
"flagged": 0,
"admin_confirmed": 0,
"flagged_reason": null,
"species": [
{
"id": 31,
"display_name": "Zostera marina"
}
],
"user": {
"id": 3793,
"username": "StrangerPaul",
"avatar": "/media/defaults/avatar-blank.jpg"
}
},
{
"id": 7381,
"created_at": "2023-09-05T03: 14: 13.000000Z",
"updated_at": "2023-09-05T03: 14: 13.000000Z",
"user_id": 3530,
"photo_path": "/media/sightings/2023-09/1693901653155183970.jpg",
"thumb_path": "/media/sightings/2023-09/1693901653155183970_thumbnail.jpg",
"latitude": 50.710415,
"longitude": -1.47068,
"accuracy": 1000,
"date_spotted": "2023-09-05",
"mobile_upload": 1,
"observe": 0,
"extensive": 0,
"length": 0,
"flowers": 0,
"sediment": 0,
"algae": 0,
"boats": 0,
"moorings": 0,
"intertidal": 0,
"damages": null,
"changes": null,
"additional_species": null,
"country": "United Kingdom",
"country_code": "GB",
"country_area": "Yarmouth",
"fishing": 0,
"fishing_gear": null,
"fishing_caught": null,
"depth": 0,
"confidence": 2,
"flagged": 0,
"admin_confirmed": 0,
"flagged_reason": null,
"species": [
{
"id": 31,
"display_name": "Zostera marina"
}
],
"user": {
"id": 3530,
"username": "FionaJ",
"avatar": "/media/defaults/avatar-blank.jpg"
}
}
]Get Nearby Sightings
GET
https://api.seagrassspotter.org
/v1/sighting/nearby
Gets sightings near a coordinate
Finds sightings near to a lat/lon, and orders them by distance.
The distance_to_parent field is the distance in metres to the provided point.
Query Parameters
latitude
number
The latitude to search
Example:
51.243
longitude
number
The longitude to search
Example:
2.67
curl --request GET \
--get "https://api.seagrassspotter.org/v1/sighting/nearby?latitude=51.243&longitude=2.67"[
{
"id": 961,
"created_at": "2017-07-11T12:06:19.000000Z",
"updated_at": "2017-07-11T12:08:30.000000Z",
"user_id": 15,
"photo_path": "/media/sightings/2017-07/1527796065662187290.jpg",
"thumb_path": "/media/sightings/2017-07/1527796065662187290_thumbnail.jpg",
"latitude": 50.771208,
"longitude": 0.154504,
"accuracy": 25,
"date_spotted": "2017-07-02",
"mobile_upload": 0,
"observe": 1,
"extensive": 3,
"length": 6,
"flowers": 4,
"sediment": 3,
"algae": 2,
"boats": 4,
"moorings": 4,
"intertidal": 2,
"damages": "",
"changes": "",
"additional_species": "",
"country": "United Kingdom",
"country_code": "GB",
"country_area": "East Sussex",
"fishing": 0,
"fishing_gear": "",
"fishing_caught": "",
"depth": 0,
"confidence": 3,
"flagged": 0,
"admin_confirmed": 0,
"flagged_reason": "",
"distance_to_parent": 27639,
"species": [
{
"id": 57,
"display_name": "Ruppia maritima"
}
],
"user": {
"id": 15,
"username": "runswo",
"avatar": "/media/profile-images/1479398726878_61348.jpg"
}
},
{
"id": 962,
"created_at": "2017-07-11T12:08:51.000000Z",
"updated_at": "2017-07-11T12:10:04.000000Z",
"user_id": 15,
"photo_path": "/media/sightings/2017-07/1527796067359156907.jpg",
"thumb_path": "/media/sightings/2017-07/1527796067359156907_thumbnail.jpg",
"latitude": 50.768697,
"longitude": 0.152386,
"accuracy": 25,
"date_spotted": "2017-07-02",
"mobile_upload": 0,
"observe": 1,
"extensive": 3,
"length": 6,
"flowers": 4,
"sediment": 3,
"algae": 2,
"boats": 4,
"moorings": 4,
"intertidal": 2,
"damages": "",
"changes": "",
"additional_species": "",
"country": "United Kingdom",
"country_code": "GB",
"country_area": "East Sussex",
"fishing": 0,
"fishing_gear": "",
"fishing_caught": "",
"depth": 0,
"confidence": 3,
"flagged": 0,
"admin_confirmed": 0,
"flagged_reason": "",
"distance_to_parent": 27839,
"species": [
{
"id": 57,
"display_name": "Ruppia maritima"
}
],
"user": {
"id": 15,
"username": "runswo",
"avatar": "/media/profile-images/1479398726878_61348.jpg"
}
}
]Get A Sighting
GET
https://api.seagrassspotter.org
/v1/sighting/{id}
Gets a single sighting.
Along with the raw sighting data, it also includes basic information about the user who submitted it.
If you pass the optional nearby parameter, it will also include up to 3
random sightings from within a 20km range as an array under the nearby property.
URL Parameters
id
integer
The ID of the sighting
Example:
7353
Query Parameters
nearby
boolean
Also include up to 3 nearby sightings
Example:
1
curl --request GET \
--get "https://api.seagrassspotter.org/v1/sighting/7353?nearby=1"{
"id": 7353,
"created_at": "2023-08-20T10:15:56.000000Z",
"updated_at": "2023-08-20T10:15:56.000000Z",
"user_id": 3494,
"photo_path": "/media/sightings/2023-08/1692544556456756752.jpg",
"thumb_path": "/media/sightings/2023-08/1692544556456756752_thumbnail.jpg",
"latitude": -8.519691,
"longitude": 119.586697,
"accuracy": 300,
"date_spotted": "2023-08-20",
"mobile_upload": 0,
"observe": 3,
"extensive": 3,
"length": 1,
"flowers": 4,
"sediment": 4,
"algae": 2,
"boats": 1,
"moorings": 4,
"intertidal": 2,
"damages": "trampling, as it is a popular tourism destination",
"changes": null,
"additional_species": null,
"country": "Indonesia",
"country_code": "ID",
"country_area": "West Manggarai Regency",
"fishing": 4,
"fishing_gear": null,
"fishing_caught": null,
"depth": 1,
"confidence": 1,
"flagged": 0,
"admin_confirmed": 0,
"flagged_reason": null,
"nearby": [
{
"id": 7352,
"created_at": "2023-08-20T10:02:47.000000Z",
"updated_at": "2023-08-20T10:02:47.000000Z",
"user_id": 3494,
"photo_path": "/media/sightings/2023-08/1692543767535662993.jpg",
"thumb_path": "/media/sightings/2023-08/1692543767535662993_thumbnail.jpg",
"latitude": -8.498471,
"longitude": 119.7578,
"accuracy": 200,
"date_spotted": "2023-08-18",
"mobile_upload": 0,
"observe": 3,
"extensive": 7,
"length": 3,
"flowers": 4,
"sediment": 2,
"algae": 2,
"boats": 1,
"moorings": 1,
"intertidal": 2,
"damages": "it's a popular snorkeling site, so trampling intensity is high. many boats operated nearby may be a threat, and I observed at least one instance of anchor laid down on the seagrass meadow.",
"changes": null,
"additional_species": "Chocolate chip sea star, lots of different fishes (can't ID)",
"country": "Indonesia",
"country_code": "ID",
"country_area": "West Manggarai Regency",
"fishing": 4,
"fishing_gear": null,
"fishing_caught": null,
"depth": 1,
"confidence": 2,
"flagged": 0,
"admin_confirmed": 0,
"flagged_reason": null,
"distance_to_parent": 18954,
"species": [
{
"id": 5,
"display_name": "Cymodocea rotundata"
},
{
"id": 7,
"display_name": "Enhalus acoroides"
},
{
"id": 21,
"display_name": "Halophila ovalis"
},
{
"id": 28,
"display_name": "Thalassia hemprichii"
}
],
"user": {
"id": 3494,
"username": "a150401d",
"avatar": "/media/profile-images/16813166118756_66150.png"
}
}
],
"species": [
{
"id": 21,
"display_name": "Halophila ovalis"
}
],
"user": {
"id": 3494,
"username": "a150401d",
"avatar": "/media/profile-images/16813166118756_66150.png"
}
}Users
Get A User
GET
https://api.seagrassspotter.org
/v1/user/{id}
Gets a single user.
Along with the user profile data, it also includes all of their sightings and absence recordings.
This will only return publicly available user data, not things like their email.
URL Parameters
id
string
The username of the user
Example:
runswo
curl --request GET \
--get "https://api.seagrassspotter.org/v1/user/runswo"{
"id": 15,
"username": "runswo",
"created_at": "2015-10-15T16:16:35.000000Z",
"updated_at": "2023-06-06T05:20:41.000000Z",
"access_level": 4,
"name": "Richard Unsworth",
"location": "Bridgend",
"organisation": "Project Seagrass",
"bio": "Marine Ecologist, Director of Project Seagrass",
"website": "http://www.swansea.ac.uk/staff/science/biosciences/r.k.f.unsworth/",
"twitter": "https://twitter.com/@zosterar",
"linkedin": "https://www.linkedin.com/in/richardunsworth",
"usertype": 1,
"avatar": "/media/profile-images/1479398726878_61348.jpg",
"sightings": [
{
"id": 13,
"created_at": "2015-10-16T08:20:16.000000Z",
"updated_at": "2023-06-09T05:18:29.000000Z",
"user_id": 15,
"photo_path": "/media/sightings/2015-10/152779521002897188.jpg",
"thumb_path": "/media/sightings/2015-10/152779521002897188_thumbnail.jpg",
"latitude": 52.942576,
"longitude": -4.564643,
"accuracy": 50,
"date_spotted": "2015-10-04",
"mobile_upload": 0,
"observe": 0,
"extensive": 0,
"length": 0,
"flowers": 0,
"sediment": 0,
"algae": 0,
"boats": 0,
"moorings": 0,
"intertidal": 0,
"damages": "",
"changes": "",
"additional_species": "",
"country": "United Kingdom",
"country_code": "GB",
"country_area": "Pwllheli",
"fishing": 0,
"fishing_gear": "",
"fishing_caught": "",
"depth": 0,
"confidence": 3,
"flagged": 0,
"admin_confirmed": 1,
"flagged_reason": "",
"species": [
{
"id": 31,
"display_name": "Zostera marina"
}
],
"user": {
"id": 15,
"username": "runswo",
"avatar": "/media/profile-images/1479398726878_61348.jpg"
}
},
{
"id": 20,
"created_at": "2015-11-01T16:16:36.000000Z",
"updated_at": "2023-06-09T05:18:30.000000Z",
"user_id": 15,
"photo_path": "/media/sightings/2015-11/1527795210512382090.jpg",
"thumb_path": "/media/sightings/2015-11/1527795210512382090_thumbnail.jpg",
"latitude": 49.939878,
"longitude": -6.330704,
"accuracy": 50,
"date_spotted": "2015-07-10",
"mobile_upload": 0,
"observe": 3,
"extensive": 7,
"length": 9,
"flowers": 3,
"sediment": 4,
"algae": 1,
"boats": 4,
"moorings": 4,
"intertidal": 0,
"damages": "",
"changes": "",
"additional_species": "Scyliorhinus stellaris",
"country": "United Kingdom",
"country_code": "GB",
"country_area": "Isles of Scilly",
"fishing": 0,
"fishing_gear": "",
"fishing_caught": "",
"depth": 0,
"confidence": 3,
"flagged": 0,
"admin_confirmed": 1,
"flagged_reason": "",
"species": [
{
"id": 31,
"display_name": "Zostera marina"
}
],
"user": {
"id": 15,
"username": "runswo",
"avatar": "/media/profile-images/1479398726878_61348.jpg"
}
}
],
"absences": [
{
"id": 11,
"created_at": "2023-06-15T09:18:52.000000Z",
"updated_at": "2023-06-15T09:18:52.000000Z",
"user_id": 15,
"photo_path": "/media/absence/2023-06/1686838732505438500.jpg",
"thumb_path": "/media/absence/2023-06/1686838732505438500_thumbnail.jpg",
"latitude": 51.529978,
"longitude": 0.803954,
"accuracy": 1000,
"date_spotted": "2023-06-15",
"mobile_upload": 1,
"sediment": 2,
"status": 0,
"habitat": 1,
"comments": null,
"country": "United Kingdom",
"country_code": "GB",
"country_area": "Southend-on-Sea",
"flagged": 0,
"admin_confirmed": 0,
"flagged_reason": null,
"user": {
"id": 15,
"username": "runswo",
"avatar": "/media/profile-images/1479398726878_61348.jpg"
}
}
]
}