To authenticate with the Skylight API, you will need to include a valid Skylight username and password in a getToken request:

curl -X POST \
    -H "Content-Type: application/json" \
    -d '{"query":"{getToken(username: \"YOUR_SKYLIGHT_USERNAME\", password: \"YOUR_SKYLIGHT_PASSWORD\") \
    {access_token expires_in}}"}' \
    https://api.skylight.earth/graphql

The response will contain an access_token value to be used in subsequent API requests:

{
  "data": {
    "getToken": {
      "access_token": "YYOdIqB48ZDS3OJpWHJxrjku1Gh0Yl",
      "expires_in": 86400
    }
  }
}

Once you have an access_token, you can use it to authenticate your requests by including the access token in the Authorization header:

curl -X POST \
    -H 'Authorization: Bearer $ACCESS_TOKEN' \
    -H "Content-Type: application/json" \
    -d '{"query":"{vessel(vesselId: \"B:735058020:1719441624:822782:817302\"){vessel_id flag flag_code mmsi}}"}' \
    https://api.skylight.earth/graphql

Access tokens are valid for 24 hours from the time of issue. Requesting a new access token will automatically revoke any previously issued tokens.

---

Many clients of Skylight want to be able to quickly visualize large amounts of geospatial data on a map. One way to do this efficiently is to use vector tiles. The Skylight API in particular supports the use of Mapbox Vector Tiles for several of our datasets.

The Vector Tile APIs use the same request object structure as their corresponding GraphQL APIs, but the response is formatted in a protobuf encoded vector tile of the geometry features with a subset of the properties attached to each feature. For vector tile APIs, submit the request query as a json encoded string in the query parameter in the URL.

Track Subpath Vector Tiles - /vectorTiles/trackSubpath/{z}/{x}/{y}

Corresponding GraphQL API searchTrackSubpaths.

Vector Tile specific request parameters

• z, x, y: These represent the grid location of the tile being requested. These values will typically be provided by your mapping library. These values are used to determine the bounding box of the tile being requested, and replace the intersects_geometry parameter in the GraphQL API. You cannot use the intersects_geometry parameter when requesting vector tiles. Unless the query is limited to a specific vessel via the mmsi or track_id parameter, Track Subpath Tiles require a minimum zoom level (z) of 8.
• geometry_field: This specifies which geometry field you want to receive features for, as vector tiles can only return a single layer of features at a time. To build multiple layers, you will need to make multiple requests.
  Available values are path_geometry which includes the linestring of the track subpath, and midpoint_geometry which is a point for the middle of the track subpath.
• All Track Subpath vector tile requests MUST include a start_time and end_time parameter. For searches not limited to a specific vessel mmsi or track_id, the time range must be less than 31 days.
• limit, offset, sortBy: These parameters are not available for vector tile requests, as vector tiles always include all features within that tile, and the results are unsorted.

  curl -G "https://api.skylight.earth/vectorTiles/trackSubpath/9/1/2" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --data-urlencode 'query={"geometry_field":"path_geometry","start_time":{"lte":"2024-10-07T03:55:35Z"},"end_time":{"gte":"2024-10-05T03:55:35Z"}}'

---

There are two ways to paginate through datasets using the Skylight API:

1. Search After (Recommended)

Search After is a methodology of paginating by using a field with a unique and sortable value, and paginating by using the sort field as a filter in future queries. For example to search for all events that occurred on September 1st, 2024, you would apply a date filter to the startTime field, and sort the results by created in ascending order. After each page, update the created.gt filter to the created of the last record in the previous page.

searchEventsV2(
    startTime: { 'gte': '2024-09-01T00:00:00Z', 'lt': '2024-09-02T00:00:00Z'},
    sortBy: "created",
    sortDirection: "asc"
) {
    events {
        ... # your fields here
        created
    }
}

And then find the maximum created timestamp from the first page and use that as the created.gt value for the next page:

searchEventsV2(
    startTime: { 'gte': '2024-09-01T00:00:00Z', 'lt': '2024-09-02T00:00:00Z'},
    created: { 'gt': '2024-09-01T01:12:34Z'},
    sortBy: "created",
    sortDirection: "asc"
) {
    events {
        ... # your fields here
        created
    }
}

2. Limit / Offset

We do also support traditional paginating through datasets with limit and offset parameters. However, we restrict limit + offset to 10,000 records, and performance of those later queries will degrade as the offset increases. We recommend using Search After if you are loading all pages in a programmatic way. Limit / Offset can be more appropriate for User Interfaces where a user is manually paginating through the data, and likely to only look at a few pages.

searchEventsV2(
    startTime: { 'gte': '2024-09-01T00:00:00Z', 'lt': '2024-09-02T00:00:00Z'},
    limit: 100,
    offset: 400
) {
    records { /* Your field here */ }
}

Using Snapshots for Consistent Pagination

Several datasets within Skylight are updated at a very high frequency and so paginating may result in missing or duplicated results dependent on the paging strategy. To provide a consistent snapshot of the data, we expose a snapshotId field on these datasets to request the backend database to provide a consistent snapshot of the data.

For the first request, send the value of "true" for the snapshotId field to request a new snapshot. The snapshotId will be returned in the meta.snapshotId field of the response:

searchEventsV2(
    startTime: { 'gte': '2024-09-01T00:00:00Z', 'lt': '2024-09-02T00:00:00Z'},
    snapshotId: "true"
) {
    records { /* Your field here */ }
    meta { snapshotId }
}

For subsequent requests, use the snapshotId value returned in the meta.snapshotId:

searchEventsV2(
    startTime: { 'gte': '2024-09-01T00:00:00Z', 'lt': '2024-09-02T00:00:00Z'},
    snapshotId: "1234567890"
) {
    records { /* Your field here */ }
    meta { snapshotId }
}

A snapshot is kept open for 1 minute after a request, as long as you are making additional requests with the same snapshotId the snapshot will remain open. If you do not make a request within 1 minute, the snapshot will be be closed.

Snapshots are are only available on frequently updated datasets that contain the snapshotId field in the input of the search query. If the snapshotId field is not present in the input, then the dataset does not support snapshots.