Goldfish API Guide 1.1

Updated Dec 18, 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

Access Token

Where To Find Your Token

Add Token to the Header

🛥️ Vessel Search

1. Inputs

Input Variables

Definitions

Input Formats

Define Your Query

Query More Than 1 Input

2. Outputs

Output Variables

Definitions

Output Formats

Write Your Query

3. Test Example

🐟 Species Search

4. Inputs

Input Variable

Definitions

Define Your Query

5. Outputs

Output Variables

Definitions

Output Formats

Write Your Query

6. Test Example

🎣 Fishery Query

7. Inputs

Input Variables

Input Formats

Define Your Query

8. Outputs

Output Variables

Definitions

Output Formats

Write Your Query

9. Test Example

✅ MSC Fishery Query

10. Inputs

Input Variables

Input Formats

Define Your Query

11. Outputs

Output Variables

Definitions

Output Formats

12. Test Example

Test and Play on the Sandbar! 🏖️

What is the sandbar?

Sandbar Variables

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:

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:

🛥️ Vessel Search

Once the Access Token has been entered, you can begin setting up your vessel search query. To do so, you will need to:

1. Define your input parameters (Inputs)
2. Define your output parameters (Outputs)

After reading through how to set up your query, give our Test Example a try.

1. 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 10 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.

2. 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 45 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.

This nested variable shows all of the authorization information associated with a vessel. Optional details to view in this variable are: authType, authTransshipStatus, authTypeStartDate, authTypeEndDate, fishingLicenseNumbers, fishingLicenseTypes, speciesCodes, speciesGroups, areaGroups, areaFaos, and authSource.

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

The actual output will appear in this format:

Example of output with multiple authorizations:

Additionally, Goldfish only outputs what is in our database. If an authorization has no known information for one of the authorization variables, then that will not contain data in the output. It will display either null or [].

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)

3. 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.

🐟 Species Search

Once the Access Token has been entered, you can begin setting up your species search query. To do so, you will need to:

1. Define your input parameters (Inputs)
2. Define your output parameters (Outputs)

After reading through how to set up your query, give the Test Example a try.

4. Inputs

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

Input Variable

To query the Species Search use the 1 input parameter.

Search name by using either a species’ English common name or scientific name. This can be a partial name or full name search.

As an example, to search for the species skipjack tuna (Katsuwonus pelamis), you can use the following input variables in name:

• Skipjack tuna
• Skipjack
• Tuna
• Katsuwonus pelamis
• Katsuwonus
• Pelamis

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 searchSpecies query in the right side panel, as pictured below.

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

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 name: String , then its definition appears as seen in the image below.

Define Your Query

Step 1 - In GraphQL,  in the Species Details tab click QUERY VARIABLES.

Step 2 - A query is already populated here for you to use.

Step 3 - Click ▶️ and select Search Species. View the output!

Step 4 - To edit the input query, click into line 3 to change the variables. For the searchSpecies query, there is only 1 input variable to use -- name. For this example, use the new variable:

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 5 - Click  ▶️ and select Search Species. View the output!

In the output, any species that has “swordfish” found in vernaculars will appear.

5. Outputs

In GraphQL API, this section is referred to as TaxonomyOutputFields.

Output Variables

To discover information about a species, Goldfish has 9 output variables. Here is a complete list of them:

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 searchSpecies 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 alpha3Code: [String!] , then its definition appears as seen in the image below.

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).

This is the alpha3Code is the code that FAO assigns to a species or a higher taxonomic rank.

This appears as a list of all the common names associated with a single species. The language of each common name is provided in the output. As an example, here is a partial output of vernaculars for the species Katsuwonus pelamis (skipjack tuna):

The hierarchy output will display the taxonomic tree of a given species. As an example, here is the output for the species Katsuwonus pelamis (skipjack tuna):

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.

Notice there are 2 queries available: searchSpecies and searchTaxonomy. These are here so you can keep the species identifier and taxonomic hierarchy information separate. If you want to merge them into a single query searchSpecies, you are able to do so.

Step 2 - To change your output variables, add/remove variables from lines 5-8 or 14-22 depending on which query you’d like to use.

Try changing lines 5-8 to:

Then, your screen should look like this:

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

6. 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 searchSpecies 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.

🎣 Fishery Query

Once the Access Token has been entered, you can begin setting up your species search query. To do so, you will need to:

3. Define your input parameters (Inputs)
4. Define your output parameters (Outputs)

After reading through how to set up your query, give the Test Example a try.

7. Inputs  

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

Input Variables

To query the Fishery Search, you will need to enter 4 variables.

Here the 4 variables are described as Groupings, and you will need to enter 1 variable from each grouping to run the query.

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.

The authorizingCountry should be entered in as a 3-alpha ISO country code.

This is a species’ scientific name. This would be a combination of genus and species (and subspecies when applicable).

This is the 3-alpha code that the FAO assigns to a species.

This is an open search. You can be as specific or general as you’d like in your query. For reference, our Fisheries Database uses FAO gear types. You can also run the query using a specific gear type name from that dataset.

To search for an aquaculture-based fishery, do not use the gearTypes variable. This is a true/false variable. Use isFarm and set the variable to be true. The query will not run if isFarm is false.

Similar to isFarm, this is a true/false variable. To search for a fishery operating on the high seas, use the variable harvestAreaHighSeas and set your input to be true. The query will not run if this variable is false.

The harvestAreaEEZ must be entered in as the 3-alpha ISO country code.

The harvestAreaFAO must be entered as the numerical code linked to a major ocean area.

harvestAreaRFMO must be entered as an RFMO’s acronym. Here is a list of acceptable harvestAreaRFMO inputs:

CCSBT

FFA

GFCM

IATTC

ICCAT

IOTC

NAFO

NEAFC

NPFC

SEAFO

SPRFMO

WCPFC

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 lines 3, 4, 5, or 6 to change your input variables. Remember the rules for this query described in  Input Variables. There needs to always be an: authorizingCountry, species, harvestArea, and gearType in the input query.

Edit Line 4 of this query to change the speciesCode. 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.

8. Outputs

In GraphQL API this section is referred to as FisheryOutputFields.

Output Variables

To discover fishery information, Goldfish has over 2 output variables.

Definitions

The definitions are able to be accessed in the API docs on the right-hand panel as described in other chapters. Here’s a quick TL;DR on each variable:

This variable provides a Boolean true/false response to answer the question “Is this a fishery?”

fisheryDetails provides ALL information associated with a single fishery.

As an example, if you query a fishery using only the harvestAreaEEZ, but the fishery also is permitted to operate in harvestAreaRFMO and harvestAreaFAO areas. Then in the output result, the API will populate all of that information.

Output Formats

Some output variables are delivered in specific formats. Here, only the variable fisheryDetails will be discussed since there are variables nested within it. All other formatting information can be found in the GraphQL Documentation panel.

As described above in Definitions, all aspects of a fishery are described in this variable. These elements include: authorizing country, species, gear type, and harvest area information. Each element grouping will be explained individually.

This variable contains the country’s full name, 2-alpha and 3-alpha ISO codes. It will look like this:

Within fisheryDetails, the species can appear in two ways. These two versions depend on if the fishery is identified by a species’ scientific name or by a higher taxonomic rank.

If a fishery contains a species’ scientific name (species + genus + subspecies), then it will appear like so:

If a fishery identifies a species by a higher taxonomic rank, then it will appear like the code block below. For this example, it is the Phylum rank.

Notice the format of taxonRankPhylum . This is how a species variable will be structured when it is another rank. The variable will be labeled as:  taxonRank<RANK>

The gearTypes output will contain the FAO gear type information. This is similar to the structure seen in the Vessel Search. The format will appear as:

This nested variable contains harvestAreaEEZ, harvestAreaFAO, harvestAreaRFMO, and harvestAreaHighSeas.

harvestAreaEEZ contains the country’s full name, 2-alpha and 3-alpha ISO codes.

harvestAreaFAO contains the numeric code and major ocean area description.

harvestAreaRFMO contains the RFMO’ acronym and the RFMO’s full name.

harvestAreaHighSeas is a Boolean response of true/false.

An example of how all formats appear in the harvestArea variable:

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, simply delete one or the other. There are only 2 output variables available for this query.

If you delete fisheryDetails then your query should look like this:

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

9. 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 variables:

Gillnets and entangling nets (nei)

Chile

Xiphias gladius

Highseas true

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.

✅ MSC Fishery Query

Once the Access Token has been entered, you can begin setting up your MSC fishery search query. To do so, you will need to:

1. Define your input parameters (Inputs)
2. Define your output parameters (Outputs)

After reading through how to set up your query, give the Test Example a try.

10. Inputs

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

Input Variables

For the MSC Fishery Search, you can write your input parameters in one of two ways. See code block for the options labeled Option 1 and Option 2.

In total there are 5 input variables.

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.

mscFisheryCertCode is the Certificate Code that MSC assigns to a fishery during certification. Here are two examples of mscFisheryCertCodes: MSC-F-31467; F-BV-1271

This is a species’ scientific name. This would be a combination of genus and species (and subspecies when applicable).

This is the 3-alpha code that the FAO assigns to a species.

This is a species’ English common name. This variable needs to be an exact match.

This is an open search. You can be as specific or general as you’d like in your query. This query runs against MSC listed gear types.  

The harvestAreaFAO must be entered as the numerical code linked to a major ocean area. If you are selecting an inland code then you must include the 0. To reference FAO major ocean areas, click here.

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 your input variables. Remember the rules for this query described in Input Variables. There are 2 input query options.

Edit Line 3 of this query to change the mscFisheryCertCode. 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.

Step 5 - Click into line 3 to change your input variables. Here, use input query Option 2. Remember the rules for this query described in Input Variables.

Edit Line 3 of this query to change all of the input variables. 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 6 - Click  ▶️ and view the output.

11. Outputs

In GraphQL API this section is referred to as MSCFisheryOutputFields.

Output Variables

To discover fishery information, Goldfish has 2 output variables. One of these is a nested variable.

Definitions

The definitions are able to be accessed in the API docs on the right-hand panel as described in other chapters. Here’s a quick TL;DR on each variable:

This variable provides the MSC fishery status to answer the question: “is this an MSC-certified fishery?”

There are 6 output options, which are: Certified; In Assessment; In-transition to MSC; Not certified; Suspended; Withdrawn.

This is the nested variable. mscFisheryDetails provides ALL information associated with a single fishery. This will include all mscFisheryCertCodes, the MSC fishery name (mscFisheryName), and all species identifiers.

Output Formats

Some output variables are delivered in specific formats. Here, only the variable mscFisheryDetails will be discussed since there are variables nested within it. All other formatting information can be found in the GraphQL Documentation panel.

As described above in Definitions, all aspects of a fishery are described in this variable. These elements include: MSC fishery certificate codes, MSC fishery name, species, gear type, and harvest area information. Each element grouping will be explained individually.

This variable contains the fishery’s full name, as written by MSC.

This variable contains the fishery’s certificate code(s), as written by MSC. If there is more than one certificate code, then the format appears as:

Within mscFisheryDetails, the species appears in three ways. The data field speciesMSC is the exact English common name that MSC identifies in the fishery.

If a fishery identifies a species by a higher taxonomic rank, such as a Family rank, then it will appear like the code block below. This example shows the Family rank.

Note 1: Notice how the data field name changed from scientificName to taxonRankFamily to accommodate the higher rank.

Note 2: Notice the format of taxonRankFamily . This is how a species variable will be structured when it is another rank. The variable will be labeled as:  taxonRank<RANK>

The gearType output contains the MSC Fishery Geartype (mscGear) first, and then Goldfish provides the matching FAO gear type information in a structure similar to the Vessel Search output. The FAO gear type is provided to streamline your queries between vessel, fishery, and MSC fishery by using/assessing standardized data.

The format for gearType appears as:

Sometimes, one mscGear can match to multiple FAO gear types. In these instances, the format for gearType appears as:

Notice how the mscGear is the same for all 3 groupings.

In this variable, the FAO numeric code and FAO Ocean Area name are provided. If there are multiple allowed FAO areas, then the variable appears as:

12. Test Example

Let’s pull it all together! Remember the steps laid out 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 be a duplicate of the output screenshot.

Bare minimum instructions:

Step 1 - Enter your access token.

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

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 of each chapter.
3. Access a limited number of vessels and fisheries from multiple sources to test.

Sandbar Variables

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: