Goldfish API Guide 1.1

Published May 8, 2024

Access Goldfish’s paid GraphQL API [playground] https://api.goldfish.io/graphql#

Access Goldfish’s free API Sandbar for testing https://sandbar.goldfish.io/graphql 

💡If you want to see what can be built with the Goldfish API, ask your representative for access to Goldfish NET (our web-based solution).

Important Notes:

1. This is a living document. As our API updates, those changes will be reflected here.
2. If you have any questions or suggestions, please reach out to hello@goldfish.io

Table of Contents

Table of Contents

Who is the API for and what does it include?

Example 1

Example 2

Example 3

Vessel Search

1. Access Token

Where To Find Your Token

Add Token to the Header

2. Inputs

Input Variables

Definitions

Input Formats

Define Your Query

Query More Than 1 Input

3. Outputs

Output Variables

Definitions

Output Formats

Write Your Query

4. Test Example

Test and Play on the Sandbar! 🏖️

What is the sandbar?

Troubleshooting

cURL & No-Code Considerations

Who is the API for and what does it include?

Our API playground is for anyone to test data queries and assess the potential use cases for integrating Goldfish’s GraphQL API in other platforms, or building something new.

Example 1

You are a seafood importer who wants to avoid delays with customs and issues in the event of government audits.  To do this, you will need  the data provided to customs to be complete, correctly formatted and accurate, in addition to ensuring the legality of fishing vessels in your supply chain. You would use the Goldfish API to:

• check for vessel name, vessel identifiers; 
• complete missing data;
• ensure vessels are not on an IUU blacklist; and
• check for active Withhold Release Orders (WROs).

Your query might look like this:

Example 1 output:

Example 2

You work in a government agency whose mission is to protect domestic interests and combat illegal trade.  To accomplish this, you audit, and/or investigate supply chain information for validity and may want to employ risk-based targeting of imports based on IUU risk. You would use Goldfish API to screen for vessel data for mismatched identifiers (a potential indicator of fraud), presence on blacklists or active Withhold Release Orders.

Your query might look like this:

Example 2 output:

Example 3

You are a traceability provider helping your customers complete and validate data to align with a sourcing standard like the Global Dialogue on Seafood Traceability (GDST). To accomplish this, you may need to source additional vessel and fishery information than was made available to the customer from their supplier.  You would create your query with the unique key data elements required by the standard.

For GDST, your query might look like this:

Example 3 output:

Vessel Search

To search for a vessel, users need to complete three steps:

1. Enter your access token.
2. Define your input parameters (sVesselInputParam)
3. Define your output parameters (sVesselOutputFields)

1. Access Token

In GraphQL, tokens are passwords. These tokens are placed in the header. Entering a token allows you authorized access the Goldfish API 😀 

Note i: You do not need an Access Token to use the Sandbar

Note ii: Access Tokens refresh every 30 days. 

Where To Find Your Token

Step 1 - Login to your Goldfish Net account. Click API Access Token in the bottom, left corner.

The screen will show a long string of code; this is your access token. Click to copy your token.

Add Token to the Header

Step 1 - Open the GraphQL API. Your screen will look like this to start.

Step 2 - Click into HTTP HEADERS (1). The Access Token query will already be populated for you.

Step 3 - Copy your token as described in Where To Find Your Token, and input (copy/paste) it over the following code:

Step 4 - Once complete, the HTTP HEADERS (1) section should look like the image below.

Pay attention to punctuation and spacing parameters.

To double-check it's correct, scroll to the end of the HTTP HEADERS (1) section and make sure there is a quotation mark after your token. It should look like this:

2. Inputs

In the GraphQL API, vessel search inputs are referred to as sVesselInputParam

Input Variables

To query the Vessel Search use 1 or more of the 9 input parameters:

Definitions

To view all input variable definitions in the GraphQL API, follow the instructions below.

Step 1 - Click DOCS in on the right side of the window.

Step 2 - Click over the query in the right side panel, as pictured below.

Step 3 - Scroll down to the bottom of the right side panel, and click input: VesselInputParam

Step 4 - A new right side panel will appear which identifies all input variables. You can click each individual variable to see its respective definition and the TL;DR of any input formatting requirements.

If you were to click IMO: String , then its definition appears as seen in the image below.

For more detailed information on input variables, view Understanding Vessel Variables (url coming soon). That document dives deeper into the variables to provide greater context, moving past quick definitions and formatting requirements.

Input Formats

Some input variables have specific formatting requirements. In this section, only variables that have specific requirements are addressed. All other formatting information should be found in the GraphQL Documentation panel (see Definitions for instructions).

rfmoCode is used to search for a vessel within a specific RFMO. This input variable must be used in conjunction with at least one other input variable. (See Query With More Than 1 Input for more detail). Here is a list of acceptable rfmoCode inputs:

CCSBT

FFA

GFCM

IATTC

ICCAT

IOTC

NAFO

NEAFC

NPFC

SEAFO

SPRFMO

WCPFC

For more detail on these acronyms, view Understanding Vessel Variables (url coming soon).

vesselFlagCode is used to search for a specific vessel flag. This input must be used in conjunction with at least one other input variable. To search for a vessel flag, you must input the country’s 3-alpha ISO code. To determine a country’s ISO code, go to this link.

Define Your Query

Step 1 - In GraphQL,  click QUERY VARIABLES.

Step 2 - A query is already populated here for you to use. Click  ▶️ and view the output.

Step 3 - To edit the input query, click into line 3 to change the variables. Input parameters will appear automatically as you start typing them, if you ever forget them you can find them in the DOCS. The identifier written in pink is what the user will enter. For this example, use the input:

Note: Be sure to maintain the same format found in the example query.

Once the new parameters are input, your query should look like this:

Step 4 - Click  ▶️ and view the output.

Query More Than 1 Input

Step 1 - Click into Line 3 of QUERY VARIABLES.

Step 2 - Here we will set up our query for more than 1 identifier. To do so, each input parameter will be written on its own line and repeat the same format in Line 3. Do the following:

In Line 3, place a comma after the last quotation mark. Line 3 should look like this:

In Line 4, add in the variable:

Your query should look like this:

Step 3 - Click  ▶️ and view the output.

3. Outputs

In GraphQL API this section is referred to as sVesselOutputFields

Output Variables

To discover information about a vessel, Goldfish has over 30+ output variables. The GraphQL API can provide output information such as: vessel identifiers, vessel metrics, port information, a vessel’s previous history, owner details, and even baddie intel, to name a few examples.

Here is a complete list of all 40 Output variables:

Definitions

To view all output variable definitions in the GraphQL API, follow the instructions below.

Step 1 - Click DOCS in on the right side of the window.

Step 2 - Click over the query in the right side panel, as pictured below.

Step 3 - Scroll through the TYPE DETAILS in the right side panel to view all output variables. You can click each individual variable to see its respective definition and the TL;DR of any formatting information.

If you were to click vesselBeam: [VesselBeamField!] , then its definition appears as seen in the image below.

For more detailed information on output variables, view Understanding Vessel Variables (url coming soon). That document dives deeper into the variables to provide greater context, moving past quick definitions and formatting requirements.

Output Formats

Some output variables are delivered in specific formats. In this section, only variables that have additional format information are addressed. All other formatting information can be found in the GraphQL Documentation panel (see Definitions for instructions).

In Goldfish, ISO country codes are used to identify any country. Here, for both vesselFlag and buildCountry, the output is the ISO country name.

This is a catch-all column for unformatted data. For more details on what specific schema can be found in this column, view Understanding Vessel Variables (url coming soon).

The following associate types are found in associatesDetails: owner; operator; operating company; beneficial owner; master; fish master; charterer; charter; captain; and ship builder. For each type we will provide the name/company name, address, and country when available.

To write the query for associatesDetails, format it as seen in the code block below. If you do not need all parameters within associatesDetails, then you can remove them from the query.

The actual output will appear in this format:

Example of output:

Additionally, Goldfish only outputs what is in our database. If an associate only has a known Name, and no known Address or Country data, then only the Name will be visible in the output.

The following data fields are found in previousHistory: vessel name; IRCS; MMSI; country; nationalRegistry; and portOfRegistry.

As an example, the output is formatted as such:

As described in other sections, it is important to note that Goldfish only outputs what is in our database. If a vessel does not have any previous history information for a data field, then it will not be populated in the output.

vesselBeam has 3 type options: Beam, Moulded Breadth, Extreme Breadth. These type options are available in the GraphQL Documentation panel and are defined in more detail in Understanding Vessel Variables (url coming soon).

For vesselBeam, the default selection is Beam. Unless a source dictates a specific form of type, the default type is selected for each.

To write the query for vesselBeam format it as seen in the code block below.

The actual output will appear as:

Example of output:

vesselDepth has 3 type options: Depth, Moulded Depth, Draft Depth. These type options are available in the GraphQL Documentation panel and are defined in more detail in Understanding Vessel Variables (url coming soon).

For vesselDepth, the default selection is Beam. Unless a source dictates a specific form of type, the default type is selected for each.

To write the query for vesselDepth format it as seen in the code block below.

The actual output will appear as:

Example of output:

vesselLength has multiple type options: Length Overall, Length Between Perpendiculars, Length at Waterline, Registered Length, Length. These type options are available in the GraphQL Documentation panel and are defined in more detail in Understanding Vessel Variables (url coming soon).

vesselLength will always identify the type in the output.

To write the query for vesselLength format it as seen in the code block below.

The actual output will appear in this format:

Example output:

vesselTonnage has multiple type options: Gross Register Tonnage, Gross Tonnage, Net Tonnage, Tonnage. These type options are available in the GraphQL Documentation panel and are defined in more detail in Understanding Vessel Variables (url coming soon).

vesselTonnage will always identify a type in the output.

To write the query for vesselTonnage format it as seen in the code block below.

The actual output will appear in this format:

Example output:

The vesselCarryingCapacity indicates the total amount of fish capable of being stored on the vessel. This can be identified in different units.

To write the query for vesselCarryingCapacity use the format in the code block below.

The actual output will appear in this format:

Example output:

The vesselEnginePower can be identified/measured in different units.To write the query for vesselEnginePower use the format in the code block below.

The actual output will appear in this format:

Example output:

The vesselFishHoldVolume can be identified/measured in different units.To write the query for vesselFishHoldVolume use the format in the code block below.

The actual output will appear in this format:

Example output:

gearTypes are standardized to the 2016 version of FAO ISSCFG. In the output you can receive the geartype name (faoName), the standard abbreviation (faoAlpha), and ISSCFG code (faoISSCFG).

To write your gearTypes query, format it like the code block below.

As an example, the output is formatted as:

vesselType follows a similar format as the gearTypes. vesselType is standardized to FAO ISSCFV. Depending on your output query, you can receive the vessel type category (faoCat) , subcategory (faoSubCat), the standard abbreviation (faoAlphaCode), and the ISSCFV code (faoISSCFV) .

To write your vesselType query, format it like the code block below.

Example output:

Write Your Query

Step 1 - In GraphQL, a query is already populated here for you to use. All output variables are written in the main section.

Step 2 - To change your output variables, delete lines 6 - 38. In Line 6, begin typing your desired output variables. Variables will appear automatically as you start typing them, and if you ever forget them you can find them in the DOCS. Each variable should have their own line.

Try changing your output variables to:

Then, your screen should look like this:

Step 3 - Click  ▶️ and view your output. (this is using the populated input variable)

4. Test Example

Let’s bring together everything learned in: Access Token, Inputs, and Outputs

For this test, you will be given the desired input and output variables. At the end of this test, your output should mimic the output screenshot.

Bare minimum instructions:

Step 1 - Enter your access token.

Step 2 - Set up your query using the input variable:

Step 3 - Use the output variables:

Step 4 - Click  ▶️ and view the output. Congrats, you did it! 🎉

Your output should look the same as the screen below.

Test and Play on the Sandbar! 🏖️

Access the sandbar at https://sandbar.goldfish.io/graphql 

What is the sandbar?

In short, Goldfish’s sandbar is a sandbox, a playground, testing environment, and whatever you want to call it for Goldfish’s GraphQL API. Input and output variables are updated with our production system, however it is a limited dataset. This will allow those developing for or assessing our API to experience the utilities of the paid version, with the exception that it does not access our production environment. In addition, unlike our production environment, it is not optimized for performance. Please keep this in mind when running your tests.

Benefits of using Sandbar:

1. You do not need an Access Token! You read that right - just start your query!
2. Access to all variables described in Inputs and Outputs
3. Access a limited number of vessels from multiple sources to test

View all Sandbar input variables here to start testing

Troubleshooting

cURL & No-Code Considerations

Some no-code platforms may require you to use a header, whereas something as Postman may not.

For non-technical users: cURL is a tool that lets you send and receive data over the internet, acting like a digital postman for websites and servers. It helps developers ensure websites run smoothly.

cURL solution for the Sandbar:

Example of what your terminal should look like: