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.

Example request:
curl --request GET \
    --get "https://api.seagrassspotter.org/v1/absence"
Example response:
[
    {
        "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
required

The ID of the sighting

Example:
53

Query Parameters

nearby
boolean

Also include up to 3 nearby absences

Example:
1
Example request:
curl --request GET \
    --get "https://api.seagrassspotter.org/v1/absence/53?nearby=1"
Example response:
{
    "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.

Example request:
curl --request GET \
    --get "https://api.seagrassspotter.org/v1/sighting"
Example response:
[
    {
        "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
required

The latitude to search

Example:
51.243
longitude
number
required

The longitude to search

Example:
2.67
Example request:
curl --request GET \
    --get "https://api.seagrassspotter.org/v1/sighting/nearby?latitude=51.243&longitude=2.67"
Example response:
[
    {
        "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
required

The ID of the sighting

Example:
7353

Query Parameters

nearby
boolean

Also include up to 3 nearby sightings

Example:
1
Example request:
curl --request GET \
    --get "https://api.seagrassspotter.org/v1/sighting/7353?nearby=1"
Example response:
{
    "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
required

The username of the user

Example:
runswo
Example request:
curl --request GET \
    --get "https://api.seagrassspotter.org/v1/user/runswo"
Example response:
{
    "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"
            }
        }
    ]
}