To help you get familiar with Skylight's GraphQL API, the following example will instruct you on building a query that returns Dark Rendezvous and Standard Rendezvous events between May 1, 2023 and May 2, 2023. To make things easier, the return is limited to only one page with five events.

Full documentation for the Skylight GraphQL API can be found here: https://api.skylight.earth/schema/query.doc.html

Getting Started

• Download and install Postman

• Download and open the sample collection file and environment variable file

After opening Postman, import the environment variables file and the collections that contains the sample queries

Importing Environment Variables

The sample file uses environment variable so that you can pass in URL and access token for different queries instead of entering them manually for each query. We created the file for you to get started.

Further Postman documentation on how to setup, manage and access environment variable for your queries can be found here:

https://learning.postman.com/docs/sending-requests/managing-environments/#creating-environments

.

To import the environment variables file:

1. Click on Environments tab

2. Import the *.postman_environment.json

You will see the {{base_url}} and {{access_token}}

Open

Importing the Collection

1. Click on Collections

2. Import the *.postman_collection.json. You will see the GraphQL collection added to the list.

Open

Running the Queries

Set the environment

Before running the query, you need to set your environment. Click on the “No environment” drop down as shown below and select the environment file you imported.

For each query, the value for the {{base_url}} is https://api.skylight.earth. Since {{base_url}} is an environment variable, you can pass in this variable or any variables automatically.

Generate an access token

To generate an access token, run the getToken query first. This token will expire after 24 hours. Do not attempt to generate a new session while the token is active. The platform doesn't allow two active sessions open for the same user and doing so will end the active session. For the following queries, the access_token will be automatically passed on. To see the automation used to run the access_token, see the Tests tab. The username and password in the getToken query are the same username and password you use to log into the Skylight app. If you do not have a Skylight login, please contact us to request an account.

Open the “getToken” file, select the “Body” tab and enter your username and password. Click send to run the query.

In the sample GraphQL collection, click “inline - get events dark_rendezvous & standard rendezvous” to see the sample Postman query.

You will see a Postman query for "events" below. This query can be used to return all event types, although in our example we will be returning only Dark and Standard Rendezvous.

Input Fields

For our example we will run a query that returns Dark Rendezvous and Standard Rendezvous events between May 1, 2023 and May 2, 2023. The results will be limited to only 1 page where each page returns 5 events. The following arguments are used to filter the results:
‍

1. eventTypes: [standard_rendezvous, dark_rendezvous]

2. startTime: “2023-05-01T00:00:00”

3. endTime: “2023-05-02T00:00:00”

4. pageNum: 1

5. pageSize: 5

Other arguments are available as shown below. You will find the list of all arguments allowed to use as the input parameter for “events” and other fields here: http://api.skylight.earth/schema/query.doc.html .

One of the arguments used in the sample query is eventType. This filter is a list that contains a pre-defined value. Since we want to get a list of Dark Rendezvous and Standard Rendezvous events, we need to look at eventTypes to see the value assigned for this object. You will see “dark_rendezvous” and “standard_rendezvous” are the two values we need for our query.

Output Fields

With GraphQL you can select from all fields which need to be returned. For this query example we want this information:
‍

• event_id

• event_type

• start

• end

• vessels:

  • vessel_0

    • country_filter

    • display_country

    • name

    • mmsi

    • vessel_id

  • vessel_1

    • country_filter

    • display_country

    • name

    • mmsi

    • vessel_id

Below is an example of items that are available as an output for Event Object

You can find the full list for the items returned in the query under Objects section (Events , Event, Start, End and EmbeddedVessel)

Running the query gives a response similar to the below:

Event Type Specific Response

Response fields in Event and EventDetails might be tied to a specific event type hence it will only return a result when your arguments is containing that event. Below is the matrix of fields: