Difference between revisions of "NEAFC2ICES WS"
From D4Science Wiki
(→Endpoint) |
|||
| (7 intermediate revisions by the same user not shown) | |||
| Line 13: | Line 13: | ||
=== API === | === API === | ||
==== Endpoint ==== | ==== Endpoint ==== | ||
| − | The test WS endpoint is currently [http://figisapps.fao.org/vrmf/neafc2ices http://figisapps.fao.org/vrmf/neafc2ices] with specific services detailed in the following paragraphs. | + | The test WS endpoint is currently [http://figisapps.fao.org/vrmf/neafc2ices/services/exchange 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: | The specific data-export services can be invoked with the following URL: | ||
| − | http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/export/{data}(/current|?{params}) | + | GET http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/services/exchange/export/{data}(/current|?{params}) |
where {data} is one among: | where {data} is one among: | ||
| Line 28: | Line 28: | ||
==== Retrieve vessel data ==== | ==== Retrieve vessel data ==== | ||
| − | This service extracts all the vessel data currently available, regardless of | + | 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). |
| − | + | ||
| − | RID LENGTH_CATEGORY POWER_CATEGORY VESSEL_TYPE FISHING_GEAR | + | 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: | ||
| + | {| class="wikitable sortable" border="1" cellpadding="4" cellspacing="0" | ||
| + | |- style="background-color:#F2F2F2" | ||
| + | ! Length type !! >= !! < !! Category | ||
| + | |- | ||
| + | || LOA||0||24||A | ||
| + | |- | ||
| + | || PP||0||20||A | ||
| + | |- | ||
| + | || LOA||24||40||B | ||
| + | |- | ||
| + | || PP||20||35||B | ||
| + | |- | ||
| + | || LOA||40||60||D | ||
| + | |- | ||
| + | || PP||35||55||D | ||
| + | |- | ||
| + | || LOA||60||||C | ||
| + | |- | ||
| + | || PP||55||||C | ||
| + | |- | ||
| + | ||Default||||||U | ||
| + | |} | ||
| + | *POWER_CATEGORY: the vessel power category, according to the following conversion table: | ||
| + | {| class="wikitable sortable" border="1" cellpadding="4" cellspacing="0" | ||
| + | |- style="background-color:#F2F2F2" | ||
| + | ! Power type !! >= !! < !! Category | ||
| + | |- | ||
| + | || HP||0||1500||A | ||
| + | |- | ||
| + | || KW||0||1150||A | ||
| + | |- | ||
| + | || HP||1500||3000||B | ||
| + | |- | ||
| + | || KW||1150||2250||B | ||
| + | |- | ||
| + | || HP||3000||4500||D | ||
| + | |- | ||
| + | || KW||2250||3350||D | ||
| + | |- | ||
| + | || HP||4500||||C | ||
| + | |- | ||
| + | || KW||3350||||C | ||
| + | |- | ||
| + | ||Default||||||U | ||
| + | |} | ||
| + | *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 ===== | ||
| + | |||
| + | #GET [http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/export/vessels/current 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) | ||
| + | #GET [http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/export/vessels?dateFrom=20120101&dateTo=20120630 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 ===== | ||
| + | |||
| + | #GET [http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/export/authorizations/current 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) | ||
| + | #GET [http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/export/authorizations?dateFrom=20120101&dateTo=20120630 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 ===== | ||
| + | |||
| + | #GET [http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/export/positions/current 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) | ||
| + | #GET [http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/export/positions?dateFrom=20120101&dateTo=20120630 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 ===== | ||
| + | |||
| + | #GET [http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/export/catch/current 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) | ||
| + | #GET [http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/export/catch?dateFrom=20120101&dateTo=20120630 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 ===== | ||
| + | |||
| + | #GET [http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/export/all/current 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) | ||
| + | #GET [http://figisapps.fao.org/vrmf/neafc2ices/services/exchange/export/all?dateFrom=20120101&dateTo=20120630 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) | ||
Latest revision as of 15:07, 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:
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 |
|---|---|---|---|
| LOA | 0 | 24 | A |
| PP | 0 | 20 | A |
| LOA | 24 | 40 | B |
| PP | 20 | 35 | B |
| LOA | 40 | 60 | D |
| PP | 35 | 55 | D |
| LOA | 60 | C | |
| PP | 55 | C | |
| Default | U |
- POWER_CATEGORY: the vessel power category, according to the following conversion table:
| Power type | >= | < | Category |
|---|---|---|---|
| HP | 0 | 1500 | A |
| KW | 0 | 1150 | A |
| HP | 1500 | 3000 | B |
| KW | 1150 | 2250 | B |
| HP | 3000 | 4500 | D |
| KW | 2250 | 3350 | D |
| HP | 4500 | C | |
| KW | 3350 | C | |
| Default | U |
- 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
- 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)
- 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
- 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)
- 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
- 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)
- 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
- 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)
- 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
- 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)
- 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)
