Trawl Event - FishServe Event.pdf · Seabird Capture Details Mandatory for Trawl Event and if...

Trawl Event The sections below describe the information necessary to create, get and update a trawl event.

Create

Request URL:

POST https://ers.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/trawl/{eventID}

Example:

POST https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/trawl/5ba04c30-c81a-4618-898e-e832da93cf98

Create URL Parameters:

Parameter Required Data type Description

Client Number Mandatory String The main permit holder client number that the event is submitted against.

Event ID Mandatory String Unique logbook generated ID for an event.

Request Header:

Content-Type: application/json

Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook)

Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)

Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)

Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

Parameter Required Data Type Description

Event ID Mandatory String Unique logbook generated ID for an event. The same event ID as defined in the URL.

Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not

Vessel Number Mandatory String If the fishing took place on a vessel, then the vessel must be identified. Must be a valid vessel number.

Notes Optional String The Fisher may record additional information relating to the event.

Method Mandatory String Must be a valid Method for the Fishing Event Type. E.g. the BT method must be reported through the Trawl Fishing Event.

Target Species Code Mandatory String Must be a valid species.

Mitigation Devices Used Optional Array of Strings List all mitigation devices used. Must be a valid mitigation device.

Start Date Time Mandatory String Must provide a date, 24 hr time and UTC offset. Date time of deployment of net(s).

Start Location Mandatory Geolocation See Start Location Parameters below. Location where the net(s) were deployed.

Is Non Fish Or Protected Species Catch Present

Mandatory Boolean The Fisher is to state whether or not they have caught any non-fish or protected species.

Number of Nets Mandatory Number Must be a whole number that is greater than 0.

Vessel Pair Number Optional String If a pair method is used, this is the other vessel involved in the fishing. Note - this vessel is not required to report.

Wing Spread Meters Mandatory Number Can provide up to 2 decimal places. Must be greater than 0.


Headline Height Meters Mandatory Number Can provide up to 2 decimal places. Must be greater than 0.

Min Mesh Size Mm Mandatory Number Can provide up to 2 decimal places. Must be greater than 0.

Ground Rope Depth Meters Mandatory Number Can provide up to 2 decimal places. Must be greater than 0.

Bottom Depth Meters Mandatory Number Can provide up to 2 decimal places. Must be greater than 0.

Speed Knots Mandatory Number Can provide up to 2 decimal places. Must be greater than 0.

Is Net Lost Conditional Boolean Records if the net has been lost and unable to be hauled.

Net at Depth Date Time Mandatory String Must provide a date, 24 hr time and UTC offset. Date Time when net(s) at depth. If not provided, ‘Is Net Lost’ must be true.

Net at Depth Location Mandatory Geolocation See Net at Depth Location Parameters below. Location when net(s) at depth. If not provided, ‘Is Net Lost’ must be true.

Net Leave Depth Date Time Mandatory String Must provide a date, 24 hr time and UTC offset. Date time when net(s) leave depth. If not provided, ‘Is Net Lost’ must be true.

Net Leave Depth Location Mandatory Geolocation See Net Leave Depth Location Parameters below. Location when net(s) leave depth. If not provided, ‘Is Net Lost’ must be true.

Finish Date Time Mandatory String Must provide a date, 24 hr time and UTC offset. Date Time when net(s) are on deck.

Finish Location Mandatory Geolocation See Finish Location Parameters below. Location when net(s) on deck.


Codend Date Time Mandatory String Must provide a date, 24 hr time and UTC offset. If not provided, ‘Is Net Lost’ must be true.

Estimated Catch Kg Mandatory Number If estimated catch > 0, then Catch must be provided. If estimated catch = 0 and Catch is provided, the ERS will still accept the event. Can provide up to 2 decimal places.

Catches Mandatory if

Estimated Catch > 0

Array See Catches Parameters below.

Non Fish or Protected Species Mandatory if Is Non

Fish Or Protected

Species Catch

Present is ‘Yes’

Array See Non Fish or Protected Species Parameters below.

Start Location Parameters:


Start Latitude Mandatory String Must provide at least 4 decimal places.

Start Longitude Mandatory String Must provide at least 4 decimal places.

Is Start Location Manual Mandatory Boolean Identifies if the GPS details have been altered by the Fisher.

Net at Depth Location Parameters:


Net at Depth Latitude Mandatory String Must provide at least 4 decimal places.

Net at Depth Longitude Mandatory String Must provide at least 4 decimal places.


Is Net at Depth Location Manual Mandatory Boolean Identifies if the GPS details have been altered by the Fisher.

Net Leave Depth Location Parameters:


Net Leave Depth Latitude Mandatory String Must provide at least 4 decimal places.

Net Leave Depth Longitude Mandatory String Must provide at least 4 decimal places.

Is Net Leave Depth Location Manual Mandatory Boolean Identifies if the GPS details have been altered by the Fisher.

Finish Location Parameters:


Finish Latitude Mandatory String Must provide at least 4 decimal places.

Finish Longitude Mandatory String Must provide at least 4 decimal places.

Is Finish Location Manual Mandatory Boolean Identifies if the GPS details have been altered by the Fisher.

Catches Parameters:


Species Code Mandatory String Must be a valid species.

Green Weight Estimate Kg Mandatory Number Can provide up to 2 decimal places.

Non Fish or Protected Species Parameters:


Species Code Mandatory String Must be provided if Non Fish Or Protected Species Catch Present is True. Valid species from the non-fish / protected species list.

Seabird Capture Details Mandatory for Trawl

Event and if

is_seabird = true

String Must be one of the following values: Warp Net Other

Estimated Weight Kg Mandatory if

measured_by =

weight

Number Must be a whole number.

Number Uninjured Mandatory if

measured_by =

count


Number Injured Mandatory if

measured_by =

count


Number Dead Mandatory if

measured_by =

count


Tag Optional Array of Strings NFPS Tag Number.

Example:

{

"eventHeader": {

"eventId": "5ba04c30-c81a-4618-898e-e832da93cf91",

"vesselNumber": "1",

"isVesselUsed": true,

"notes": "Fishing conditions were poor"

},

"method": "BT",

"targetSpeciesCode": "SNA",

"mitigationDevicesUsed": ["STR", "LAS"],

"startDateTime": "2017-04-05T09:15:00+11:00",

"startLocation": {

"longitude": "174.732177",

"latitude": "-41.409898",

"isManual": false

},

"numberOfNets": 3,

"vesselPairNumber": null,

"wingSpreadMetres": 12.75,

"headlineHeightMetres": 25.5,

"minMeshSizeMm": 5.75,

"groundRopeDepthMetres": 110.5,

"bottomDepthMetres": 150.75,

"speedKnots": 7.5,

"isNetLost": false,

"finishDateTime": "2017-05-04T12:30:00+13:00",

"finishLocation": {

"longitude": "174.6799",

"latitude": "-41.4289",

"isManual": false

},

"NetAtDepthDateTime": "2017-05-04T10:00:00+13:00",

"NetAtDepthLocation": {

"longitude": "174.732187",

"latitude": "-41.409998",

"isManual": false

},

"NetLeaveDepthDateTime": "2017-05-04T11:30:00+13:00",

"NetLeaveDepthLocation": {

"longitude": "174.6799",

"latitude": "-41.4289",

"isManual": false

},

"codendDateTime": "2017-05-04T12:15:00+13:00",

"estimatedCatchKg": 90,

"catches": [

{

"speciesCode": "SNA",

"greenWeightEstimateKg": 50.25,

},

{

"speciesCode": "HOK",

"greenWeightEstimateKg": 25,

},

],

"isNonFishOrProtectedSpeciesCatchPresent": false,

"nonFishOrProtectedSpeciesCatches": [

{

"speciesCode": "XAF",

"seabirdCaptureDetails": "Warp",

"estimatedWeightKg": null,

"numberUninjured": 2,

"numberInjured": 3,

"numberDead": 5,

"tags": ["SG101", "SG105", "SG305", "SG501", "SG111"]

},

{

"speciesCode": "DEN",

"seabirdCaptureDetails": null,

"estimatedWeightKg": 45.54,

"numberUninjured": null,

"numberInjured": null,

"numberDead": null,

"tags": ["SDG101", "DG105", "DG305", "DG501", "DG111"]

},

]

}

Response Response Status:

Status Description

201 Created Status when event has been accepted successfully.

400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.

401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Body Parameters:

Parameter Data Type Description

Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:


Property Name String The name of the property that has an error.

Attempted Value String The attempted value used.

Error Code String The type of error.


Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{

"errors": []

}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{

"errors": [

{

"propertyName": "EventId",

"attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",

"errorCode": "DuplicateValue",

"errorMessage": "EventId already exists."

}

]

}

Get

Request URL:

GET https://ers.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/trawl/{eventID}

Example:

GET https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/trawl/5ba04c30-c81a-4618-898e-e832da93cf98





Request Header:







Status Description

200 Ok Status when event has been retrieved successfully.

Status Description

404 Not Found Status when event cannot be found.



Parameter Data Type

Event ID String

Is Vessel Used Boolean

Vessel Number String

Notes String

Method String

Target Species Code String

Mitigation Devices Used Array of Strings

Start Date Time String

Start Location See Start Location Parameters below.

Geolocation

Is Non Fish Or Protected Species Catch Present

Boolean

Number of Nets Number

Vessel Pair Number String

Wing Spread Meters Number

Headline Height Meters Number

Parameter Data Type

Min Mesh Size Mm Number

Ground Rope Depth Meters Number

Bottom Depth Meters Number

Speed Knots Number

Is Net Lost Boolean

Net at Depth Date Time String

Net at Depth Location See Net at Depth Location Parameters below.

Geolocation

Net Leave Depth Date Time String

Net Leave Depth Location See Net Leave Depth Location Parameters below.

Geolocation

Finish Date Time String

Finish Location See Finish Location Parameters below.

Geolocation

Codend Date Time String

Estimated Catch Kg Number

Catches See Catches Parameters below.

Array

Non Fish or Protected Species See Non Fish or Protected Species Parameters below.

Array

Errors Array

Start Location Parameters:

Parameter Data Type

Start Latitude Number

Start Longitude Number

Parameter Data Type

Is Start Location Manual Boolean

Net at Depth Location Parameters:

Parameter Data Type

Net at Depth Latitude Number

Net at Depth Longitude Number

Is Net at Depth Location Manual Boolean

Net Leave Depth Location Parameters:

Parameter Data Type

Net Leave Depth Latitude Number

Net Leave Depth Longitude Number

Is Net Leave Depth Location Manual Boolean

Finish Location Parameters:

Parameter Data Type

Finish Latitude Number

Finish Longitude Number

Is Finish Location Manual Boolean

Catches Parameters:

Parameter Data Type

Species Code String

Green Weight Estimate Kg Number

Product State String

Processed Weight Kg Number

Number of Fish Number

Non Fish or Protected Species Parameters:

Parameter Data Type

Species Code String

Seabird Capture Details String

Estimated Weight Kg Number

Number Uninjured Number

Number Injured Number

Number Dead Number

Tag Array of Strings

Example:

{

"event": {

"numberOfNets": 3,







"speedKnots": 7.5,

"isNetLost": false,



"netAtDepthDateTime": "2017-05-04T10:00:00+13:00",

"netAtDepthLocation": {

"longitude": 174.732187,

"latitude": -41.409998,

"isManual": false

},

"netLeaveDepthDateTime": "2017-05-04T11:30:00+13:00",

"netLeaveDepthLocation": {

"longitude": 174.6799,

"latitude": -41.4289,

"isManual": false

},

"method": "BT",


"mitigationDevicesUsed": [

"STR",

"LAS"

],

"startDateTime": "2017-04-05T09:15:00+11:00",

"startLocation": {

"longitude": 174.732177,

"latitude": -41.409898,

"isManual": false

},


"finishLocation": {

"longitude": 174.6799,

"latitude": -41.4289,

"isManual": false

},


"catches": [

{



"productState": null,

"processedWeightKg": null,

"numberOfFish": null

},

{


"greenWeightEstimateKg": 25,

"productState": null,

"processedWeightKg": null,

"numberOfFish": null

},

],

"nonFishOrProtectedSpeciesCatches": [

{

"speciesCode": "XAF",

"seabirdCaptureDetails": "Warp",

"estimatedWeightKg": null,

"numberUninjured": 2,

"numberInjured": 3,

"numberDead": 5,

"tags": ["SG101", "SG105", "SG305", "SG501", "SG111"]

},

{

"speciesCode": "DEN",

"seabirdCaptureDetails": null,

"estimatedWeightKg": 45.54,

"numberUninjured": null,

"numberInjured": null,

"numberDead": null,

"tags": ["SDG101", "DG105", "DG305", "DG501", "DG111"]

},

],


"schemaEdition": 1,

"eventVersion": 1,

"clientNumber": "1234567",

"eventDateTime": "2017-04-05T09:15:00+11:00",



"notes": "Fishing conditions were poor"

},

"errors": []

}

Update

Request URL:

PUT https://ers.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/trawl/{eventID}

Example:

PUT https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/trawl/5ba04c30-c81a-4618-898e-e832da93cf98





Request Header:






Request Body Parameters:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

The amended value of the fields that need to be updated will need to be passed in the request body.


Event Version Mandatory Number The version of the event that the fisher is wanting to update.

Example:

{

"eventHeader": {


"eventVersion" : 1,



"notes": "None"

},

"startDateTime": "2017-04-05T09:15:00+11:00",

"method": "BT",


"mitigationDevicesUsed": ["HOP", "DDD"],

"startLocation": {

"longitude": "174.732177",

"latitude": "-41.409898",

"isManual": false

},


"numberOfNets": 3,







"speedKnots": 7.5,

"isNetLost": false


"finishLocation": {

"longitude": "174.6799",

"latitude": "-41.4289",

"isManual": false

},

"NetAtDepthDateTime": "2017-05-04T10:00:00+13:00",

"NetAtDepthLocation": {

"longitude": "174.732187",

"latitude": "-41.409998",

"isManual": false

},

"NetLeaveDepthDateTime": "2017-05-04T11:30:00+13:00",

"NetLeaveDepthLocation": {

"longitude": "174.6799",

"latitude": "-41.4289",

"isManual": false

},



"catches": [

{



},

{



}

],

}


Status Description

200 Ok Status when event has been updated successfully.

400 Bad Request Status when event failed to update.

Status Description

This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.




Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:


Property Name String The name of the property that has an error.

Attempted Value String The attempted value used.

Error Code String The type of error.

Error Message String The description of the error.

Example 1:

{

"errors": []

}

Example 2:

{

"errors": [

{

"propertyName": "EventVersion",

"attemptedValue": "2",

"errorCode": "InvalidValue",

"errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."

}

]

}

Trawl Event - FishServe Event.pdf · Seabird Capture Details Mandatory for Trawl Event and if...

Documents

Transcript of Trawl Event - FishServe Event.pdf · Seabird Capture Details Mandatory for Trawl Event and if...