Upload
others
View
2
Download
0
Embed Size (px)
Citation preview
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.
Parameter Required Data Type Description
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.
Parameter Required Data Type Description
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:
Parameter Required Data Type Description
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:
Parameter Required Data Type Description
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.
Parameter Required Data Type Description
Is Net at Depth Location Manual Mandatory Boolean Identifies if the GPS details have been altered by the Fisher.
Net Leave Depth Location Parameters:
Parameter Required Data Type Description
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:
Parameter Required Data Type Description
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:
Parameter Required Data Type Description
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:
Parameter Required Data Type Description
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 Must be a whole number.
Number Injured Mandatory if
measured_by =
count
Number Must be a whole number.
Number Dead Mandatory if
measured_by =
count
Number Must be a whole number.
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:
Parameter Data Type Description
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.
Parameter Data Type Description
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
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
Response Response Status:
Status Description
200 Ok Status when event has been retrieved successfully.
Status Description
404 Not Found Status when event cannot be found.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.
Response Body Parameters:
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,
"vesselPairNumber": null,
"wingSpreadMetres": 12.75,
"headlineHeightMetres": 25.5,
"minMeshSizeMm": 5.75,
"groundRopeDepthMetres": 110.5,
"bottomDepthMetres": 150.75,
"speedKnots": 7.5,
"isNetLost": false,
"codendDateTime": "2017-05-04T12:15:00+13:00",
"estimatedCatchKg": 90,
"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",
"targetSpeciesCode": "SNA",
"mitigationDevicesUsed": [
"STR",
"LAS"
],
"startDateTime": "2017-04-05T09:15:00+11:00",
"startLocation": {
"longitude": 174.732177,
"latitude": -41.409898,
"isManual": false
},
"finishDateTime": "2017-05-04T12:30:00+13:00",
"finishLocation": {
"longitude": 174.6799,
"latitude": -41.4289,
"isManual": false
},
"isNonFishOrProtectedSpeciesCatchPresent": false,
"catches": [
{
"speciesCode": "SNA",
"greenWeightEstimateKg": 50.25,
"productState": null,
"processedWeightKg": null,
"numberOfFish": null
},
{
"speciesCode": "HOK",
"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"]
},
],
"eventId": "5ba04c30-c81a-4618-898e-e832da93cf91",
"schemaEdition": 1,
"eventVersion": 1,
"clientNumber": "1234567",
"eventDateTime": "2017-04-05T09:15:00+11:00",
"vesselNumber": "1",
"isVesselUsed": true,
"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
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:
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.
Parameter Required Data Type Description
Event Version Mandatory Number The version of the event that the fisher is wanting to update.
Example:
{
"eventHeader": {
"eventId": "5ba04c30-c81a-4618-898e-e832da93cf98",
"eventVersion" : 1,
"vesselNumber": "11149",
"isVesselUsed": true,
"notes": "None"
},
"startDateTime": "2017-04-05T09:15:00+11:00",
"method": "BT",
"targetSpeciesCode": "SNA",
"mitigationDevicesUsed": ["HOP", "DDD"],
"startLocation": {
"longitude": "174.732177",
"latitude": "-41.409898",
"isManual": false
},
"isNonFishOrProtectedSpeciesCatchPresent": 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": 103,
"catches": [
{
"speciesCode": "SNA",
"greenWeightEstimateKg": 50.25,
},
{
"speciesCode": "HOK",
"greenWeightEstimateKg": 23.75,
}
],
}
Response Response Status:
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.
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:
Parameter Data Type Description
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."
}
]
}