NEAFC2ICES WS

From IMarine Wiki

Jump to: navigation, search

Contents

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|?{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:
Length type >= < Category
LOA024A
PP020A
LOA2440B
PP2035B
LOA4060D
PP3555D
LOA60C
PP55C
DefaultU
  • POWER_CATEGORY: the vessel power category, according to the following conversion table:
Power type >= < Category
HP01500A
KW01150A
HP15003000B
KW11502250B
HP30004500D
KW22503350D
HP4500C
KW3350C
DefaultU
  • 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).

Request examples
  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)
Request examples
  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
Request examples
  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'
Request examples
  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

Request examples
  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)
Personal tools