Trawl Event

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

Change history
Date Change Schema Schema Valid From Schema Valid To
01/09/2021

Released to production

Implementation of circular changes for September 2021.
21/12/2018 Released to production
11/06/2018 Added two new fields; Fishing Under HSP and Is Non Fish or Protected Species Catch Present   v2 01/07/2018
18/05/2017 Initial publication v1 01/10/2017 30/09/2018

For UAT schema valid dates click here.

Create

Request URL:

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

Example:

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

Create URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Schema Edition Mandatory String The API schema used for the format of the submitted data. For example, v1 or v2.
Event ID Mandatory String Unique logbook generated ID for an event.

Request Header:

Content-Type: application/json

Signature: signature generated from the digital signature algorithm using the request body and private key.

Request Body Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Event Header Mandatory Event Header Set See Event Header Properties below.
Fishing Under HSP Optional Boolean The Fisher can state whether they are fishing under a High Seas Permit or not.
Fishing Method Code Mandatory String

Must be a valid fishing method code for the Fishing Event Type.

Validated against Fishing Methods Master Data.

E.g. the BT method must be reported through the Trawl Fishing Event.
Mitigation Device Codes Mandatory Array of Strings Validated against Mitigation Devices for Fishing Methods master data.
Target Species Code Mandatory String

Must be a valid species.

Validated against the Fish Species master data.
Start Location Mandatory Geolocation Set See Geolocation Set Parameters below.
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.

Must be greater than 0.
Vessel Pair Number Optional String If a pair method is used, this is the other vessel involved in the fishing.

If provided, must be a valid vessel number.
Wing Spread Metres Mandatory Number Must be a whole number.

Must be greater than 0.
Headline Height Metres Mandatory Number

Decimal to 2dp.

Must be greater than 0.
Codend Mesh Size Mm Mandatory Number Must be a whole number.

Must be 0 or greater.
Ground Rope Depth Metres Mandatory Number Must be a whole number.

Must be greater than 0.
Bottom Depth Metres Mandatory Number Must be a whole number.

Must be greater than 0.
Speed Knots Mandatory Number Decimal to 2dp.

Must be greater than 0.
Is Net Lost Conditional Boolean Records if the net has been lost and unable to be hauled.
Finish Location Conditional  Geolocation Set See Geolocation Set Parameters below.

Location when net(s) on deck.

Mandatory if net has not been lost - 'Is Net Lost' is false. 

Optional if net has been lost - 'Is Net Lost' is true.
Estimated Catch Kg Mandatory Number Decimal to 2dp.

Must be 0 or greater.

If estimated catch > 0, then Catch must be provided (must have at least one catch record).

If estimated catch = 0 and Catch is provided, the ERS will still accept the event.
Catches Optional Array of Catches Can be 0 or many Catch records.

Records all species caught

See Catches Parameters below.

Event Header Properties:

ParameterRequiredData TypeValidation and Additional Notes
Event ID Mandatory String Unique logbook generated ID for an event.

The same event ID as defined in the URL.
Trip ID Mandatory String
Software Vendor Mandatory String Your software vendor name. For example, e-logbook.
Software Version Mandatory String Your software version number. For example, 1.0.0.0
Software Installation Id Mandatory String

Your software installation ID. For example, a13afab2-c409-4622-b8f8-146996587809

Must be the Software Installation Id that was registered with the user and public key.
Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String

Must be a valid client number. 

Must be the same client number as specified in the URL.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Mandatory String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.
Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset.
Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

Geolocation Set Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Date Time Mandatory String Date 24 hr + UTC Offset
Manual Date Time Optional String Date 24 hr + UTC Offset
System Location Conditional Geolocation At least one group of system or manual location parameters must be provided.

See geolocation parameters below.
Manual Location Conditional Geolocation

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees

System Location: Minimum of 4dp required.

Manual Location: Minimum of 3dp required.
Longitude Mandatory decimal degrees 

System Location: Minimum of 4dp required.

Manual Location: Minimum of 3dp required.

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String

Must be a valid ERS species code.

Validated against Fish Species master data.
Green Weight Estimate Kg Mandatory Number Decimal to 2dp.

Must be 0 or greater

Trawl Create Request Body Example:

{
  "eventHeader": {
    "tripId": "Trawltripid121",
    "eventId": "5ba04c30-c81a-4618-898e-e832da93cf9290",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Fishing conditions were poor",
    "completedDateTime": "2017-05-04T10:00:00+13:00",
    "softwareVendor": "ERS-FishServe",
    "softwareVersion": "1.1.2",
    "softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
    "clientNumber": "1234567",
    "completerUserId": "12345" 
  },
   "fishingUnderHSP": "True", 
  "fishingMethodCode": "MW",
  "targetSpeciesCode": "SNA",
  "mitigationDeviceCodes": ["BIB"],
  "startLocation": {
  "systemDateTime": "2017-05-24T08:01:00+13:00",
  "systemLocation": {
    "longitude": -175.5432,
    "latitude": -45.9878
                     },
  "manualDateTime": "2017-05-24T09:15:00+13:00",
  "manualLocation": {
     "longitude": -176.543,
     "latitude": -46.987
                    }
                   },
 "IsNonFishOrProtectedSpeciesCatchPresent": "True", 
            
  "numberOfNets": 3,
  "vesselPairNumber": null,
  "wingSpreadMetres": 12,
  "headlineHeightMetres": 25.5,
  "codendMeshSizeMm": 5,
  "groundRopeDepthMetres": 11,
  "bottomDepthMetres": 150,
  "speedKnots": 7,
  "finishLocation": {
  "systemDateTime": "2017-05-24T12:30:00+13:00",
  "systemLocation": {
      "longitude": -174.5432,
      "latitude": -44.9878
                    }
                  },
 "isNetLost": false,
  },
  "estimatedCatchKg": 90,
  "catches": [
    {
      "speciesCode": "SNA",
      "greenWeightEstimateKg": 50.25
    },
    {
      "speciesCode": "HOK",
      "greenWeightEstimateKg": 23.75
    }
  ] 
}
Response

Response Status:

StatusDescription
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 Validation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
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." 
	 } 
  ]
 }

Back to top

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/{schemaEdition}/trawl/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/trawl/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Schema Edition Mandatory String The API schema used for the format of the submitted data. For example, v1 or v2.
Event ID Mandatory String Unique logbook generated ID for an event.
Software Installation Id Mandatory String

Your software installation ID. For example, a13afab2-c409-4622-b8f8-146996587809

Must be the Software Installation Id that was registered with the user and public key.
Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

Content-Type: application/json
Signature: signature generated from the digital signature algorithm using the request URL and private key.
Response

Response Status:

StatusDescription
200 Ok Status when event has been retrieved successfully.
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:

Properties are returned within an Event parameter. Please see the example provided.

ParameterData Type
Event ID String
Trip ID String
Client Number String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Fishing Under HSP Boolean
Fishing Method Code String
Mitigation Device Codes Array of Strings
Target Species Code String
Start Location See Geolocation Set Parameters below. Geolocation Set
Is Non Fish or Protected Species Catch Present Boolean
Number of Nets Number
Vessel Pair Number String
Wing Spread Metres Number
Headline Height Metres Number
Codend Mesh Size Mm Number
Ground Rope Depth Metres Number
Bottom Depth Metres Number
Speed Knots Number
Is Net Lost Boolean
Finish Location See Geolocation Set Parameters below. Geolocation
Completed Date Time String
Estimated Catch Kg Number
Catches See Catches Parameters below. Array of Catches
Errors Array
Amendment Reason String

Geolocation Set Parameters:

ParameterData Type
System Location

See Geolocation Parameters below

 Geolocation
Manual Location

See Geolocation Parameters below

 Geolocation
System Date Time String
Manual Date Time String

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees

Catches Parameters:

ParameterData Type
Species Code String
Green Weight Estimate Kg Number

Trawl Get Request Body Example:

{
  "event": {
    "isNonFishOrProtectedSpeciesCatchPresent": "True",
  "numberOfNets": 3,
    "vesselPairNumber": null,
    "wingSpreadMetres": 12,
    "headlineHeightMetres": 25.5,
    "codendMeshSizeMm": 5,
    "groundRopeDepthMetres": 11,
    "bottomDepthMetres": 150,
    "speedKnots": 7,
    "isNetLost": false,
    "estimatedCatchKg": 90,
    },
     "fishingUnderHSP": "True",
    
    "fishingMethodCode": "MW",
    "targetSpeciesCode": "SNA",
    "mitigationDeviceCodes": [
      "BIB"
    ],
    "startLocation": {
      "systemDateTime": "2017-05-24T08:01:00+13:00",
      "systemLocation": {
        "longitude": -175.5432,
        "latitude": -45.9878
      },
      "manualDateTime": "2017-05-24T09:15:00+13:00",
      "manualLocation": {
        "longitude": -176.543,
        "latitude": -46.987
      }
    },
    "finishLocation": {
      "systemDateTime": "2017-05-24T12:30:00+13:00",
      "systemLocation": {
        "longitude": -174.5432,
        "latitude": -44.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "catches": [
      {
        "speciesCode": "SNA",
        "greenWeightEstimateKg": 50.25,
      },
      {
        "speciesCode": "HOK",
        "greenWeightEstimateKg": 23.75,
      }
    ],
    "tripId": "Trawltripid121",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "eventId": "5ba04c30-c81a-4618-898e-e832da93cf9290",
    "schemaEdition": 1,
    "eventVersion": 1,
    "clientNumber": "8462926",
    "completedDateTime": "2017-05-04T10:00:00+13:00",
    "notes": "Fishing conditions were poor",
    "amendmentReason": null,
    "completedByName": "Dirk Munroe"
  },
  "errors": []
}

Back to top

Update

Request URL:

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

Example:

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

Update URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Schema Edition Mandatory String The API schema used for the format of the submitted data. For example, v1 or v2.
Event ID Mandatory String Unique logbook generated ID for an event.

Request Header:

Content-Type: application/json
Signature: signature generated from the digital signature algorithm using the request body and private key.

Request Body Parameters:

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

This parameter is a property of the Event Header Set.

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

ParameterRequiredData TypeDescription
Event Version Mandatory Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

Trawl Update Request Body Example:

{
  "eventHeader": {
    "tripId": "Trawltripid1",
    "eventId": "5ba04c30-c81a-4618-898e-e832da93cf9290",
    "eventVersion": "2",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Fishing conditions were poor",
    "completedDateTime": null,
    "amendmentReason": "Wrong species code used",
    "softwareVendor": "ERS-FishServe",
    "softwareVersion": "1.1.2",
    "softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
    "clientNumber": "1234567",
    "completerUserId": "1234" 
  },
  "fishingUnderHSP": "True",
  "fishingMethodCode": "BT",
  "targetSpeciesCode": "SNA",
  "mitigationDeviceCodes": ["BIB"],
  "startLocation": {
    "systemDateTime": "2017-05-24T08:01:00+13:00",
       "systemLocation": {
           "longitude": -175.5432,
           "latitude": -45.9878
                                },
    "manualDateTime": "2017-05-24T09:15:00+13:00",
        "manualLocation": {
            "longitude": -176.543,
             "latitude": -46.987
                                }
  },
   "isNonFishOrProtectedSpeciesCatchPresent": "True",  
  
  "numberOfNets": 3,
  "vesselPairNumber": null,
  "wingSpreadMetres": 12,
  "headlineHeightMetres": 25.5,
  "codendMeshSizeMm": 5,
  "groundRopeDepthMetres": 11,
  "bottomDepthMetres": 150,
  "speedKnots": 7.5,
  "finishLocation": {
    "systemDateTime": "2017-05-24T12:30:00+13:00",
        "systemLocation": {
            "longitude": -174.5432,
            "latitude": -44.9878
                                }
  },
 "isNetLost": false,
  "estimatedCatchKg": 90,
  "catches": [
    {
      "speciesCode": "SNA",
      "greenWeightEstimateKg": 50.25
    },
    {
      "speciesCode": "GSH",
      "greenWeightEstimateKg": 23.75
    }
  ]
}
Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. 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:

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

Errors Parameters:

ParameterData TypeDescription
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." 
	 } 
	]
}

Back to top