Difference between revisions of "NEAFC2ICES WS"

Revision as of 15:38, 18 June 2014

Purposes

This wiki page details the API and the expected behavior of the NEAFC 2 ICES data exchange web service. Currently, the WS is hosted by FAO and provides access to a limited set of data (not intended for public use). In the future, this same WS will be made available by NEAFC and additional access constraints will apply.

Background

Please refer to this ticket for background about the purposes and rationale of this WS

Remarks

Unless a specific timeframe is explicitly requested, the extracted data will always reference information belonging to the past semester. This means that in such circumstances:

• Incoming requests sent from January 1st to June 30th will produce data related to the time period spanning from July 1st to December 31st of the previous year
• Incoming requests sent from July 1st to December 31st will produce data related to the time period spanning from January 1st to June 30th of the same year

API

Endpoint

The test WS endpoint is currently http://figisapps.fao.org/vrmf/neafc2ices with specific services detailed in the following paragraphs.

The specific data-export services can be invoked with the following URL:

http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/export/{data}(/current%7C?{params})

where {data} is one among:

• vessels (vessel details, is not related to a given timeframe)
• authorization (vessel authorization in a given timeframe)
• positions (vessel positions in a given timeframe)
• catch (catch data in a given timeframe)
• all (all of the above, in a given timeframe)

Retrieve vessel data

This service extracts all the vessel data currently available, regardless of the time frame. The produced data are anonymized, in the sense that receiving users will not be able to infer such vessel-specific details as flag, vessel name and vessel radio callsign. Each vessel appearing in this report is assigned a unique identifier which is a non-reversible, deterministic hash of some of the vessel identifiers and the chosen timeframe. This unique identifier remains constant for a given timeframe, and can be used to reference related data exported by means of the other available services (e.g. positions).

The exported data are served as an uncompressed CSV, with header, using commas as separator and double quotes as field markers and with the following columns:

• RID: the vessel unique ID
• LENGTH_CATEGORY: the vessel length category, according to the following conversion table:

• POWER_CATEGORY: the vessel power category, according to the following conversion table:

• VESSEL_TYPE: the vessel type (ISSCFV code?)
• FISHING_GEAR: the vessel gear (ISSCFG code)

This is the only service - among those currently available - that does not depend on a timeframe to produce the result set. As already said, the provided timeframe (if any) will only be used to calculate the unique id (for consistency reasons).

URL example

1. http://figisapps.fao.org/vrmf/neafc2ices/export/vessels/current to retrieve all the available vessel data (using the previous semester as timeframe of reference for UID generation purposes)
2. http://figisapps.fao.org/vrmf/neafc2ices/export/vessels?dateFrom=20120101&dateTo=20120630 to retrieve all the available vessel data (using the first semester of 2012 as timeframe of reference for UID generation purposes)

Retrieve fishing authorizations data

This service extracts the fishing authorizations data available for any of the vessel during a time frame. The produced data are linked to the vessel data via the RID column.

The exported data are served as an uncompressed CSV, with header, using commas as separator and double quotes as field markers and with the following columns:

• RID: the vessel unique ID
• SPECIES: the authorized species (ASFIS 3-alpha code)

URL example

1. http://figisapps.fao.org/vrmf/neafc2ices/export/authorizations/current to retrieve the vessel authorizations data (using the previous semester as timeframe of reference for UID generation purposes)
2. http://figisapps.fao.org/vrmf/neafc2ices/export/authorizations?dateFrom=20120101&dateTo=20120630 to retrieve the vessel authorizations data (using the first semester of 2012 as timeframe of reference for UID generation purposes)