Difference between revisions of "NEAFC2ICES WS"

Revision as of 15:06, 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/services/exchange with specific services detailed in the following paragraphs.

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

GET http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/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. GET http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/export/vessels/current to retrieve all the available vessel data (using the previous semester as timeframe of reference for UID generation purposes)
2. GET http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/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 given 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. GET http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/export/authorizations/current to retrieve the vessel authorizations data (using the previous semester as timeframe of reference for UID generation purposes)
2. GET http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/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)

Retrieve vessel positions data

This service extracts the vessel positions data available for any of the vessel during a given 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
• TM: an event code (?)
• DA: the position date (yyyyMMdd)
• TI: the position time (hhmm)
• LT: the latitude
• LG: the longitude
• SP: the speed (knots x 10)
• CO: the course

URL example

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

Retrieve vessel catch data

This service extracts the vessel catch data available for any of the vessel during a given 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
• CA_SPECIES: the authorized species (ASFIS 3-alpha code)
• CA_QUANTITY: the caught quantity
• DF: 'unclear'

URL example

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

Retrieve all data

This service extracts the full set of available data for any of the vessel during a given time frame. It is provided as a ZIP file containing one distinct CSV for each of the single available data

URL example

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