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

Transcription

1 Jigging Event The sections below describe the information necessary to create, get and update a Jigging event. Create Request URL: POST Example: POST Create URL Parameters: Parameter Required Data type Description Client Number Mandatory The main permit holder client number that the event is submitted against. Event ID Mandatory 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, ) Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c b8f ) Authorization: Bearer YOUR_USER_TOKEN

2 Request Body Parameters: Parameter Required Data Type Validation and Additional Notes Event ID Mandatory 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 Conditional If the fishing took place on a vessel, then the vessel must be identified. Must be a valid vessel number. Mandatory if 'Is Vessel Used' = True. If Is Vessel Used = False and a Vessel Number is provided, ERS will not accept the event. Notes Optional The Fisher may record additional information relating to the event. Fishing Method Code Mandatory Must be a valid Method for the Fishing Event Type. e.g a SJ code may be used for a Jigging event. Validated against the Fishing Methods master data. Mitigation Device Codes Optional Array of s Validated against the Mitigation Devices master data. Target Species Code Mandatory Must be a valid species. Validated against the Fish Species master data. Start Location Mandatory Geolocation Set See Start Geolocation Set Parameters below. Deepest Lure Depth Metres Mandatory Number Must be greater than 0. Bottom Depth Metres Mandatory Number Must be greater than 0. Depth at Start Number of Single Reels Mandatory Number Must be 0 or greater.

3 Parameter Required Data Type Validation and Additional Notes Number of Double Reels Mandatory Number Must be 0 or greater. Finish Location Mandatory Geolocation Set See Finish Geolocation 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. Completed Date Time Mandatory Must be provided for Create Must be null for Update. ERS will reject the event if provided for update. Date 24hr + UTC offset Catches Optional Array of catch Can be 0 or many Catch records. Records all species caught See Catches Parameters below. Non Fish or Protected Species Catches Conditional Array of NFPS records See Non Fish or Protected Species Parameters below. Mandatory if Is Non Fish Or Protected Species Catch Present is Yes Amendment Reason Conditional Must be provided for an Update. Must be null for Create. ERS will reject the event if provided for create. Start Geolocation Set Parameters: Parameter Required Data Type Validation and Additional Notes System Start Date Time Mandatory Date 24 hr + UTC Offset Manual Start Date Time Optional Date 24 hr + UTC Offset System Location Conditional Geolocation At least one group of system or manual location parameters must Manual Location Conditional Geolocation be provided. See system and manual location parameters below.

4 System Location Parameters: Parameter Required Data Type Validation and Additional Notes Latitude Mandatory decimal degrees, Longitude Mandatory decimal degrees, Manual Location Parameters: Parameter Required Data Type Validation and Additional Notes Latitude Mandatory decimal degrees, Longitude Mandatory decimal degrees, Finish Geolocation Set Parameters: Parameter Required Data Type Validation and Additional Notes System Finish Date Time Mandatory Date 24 hr + UTC Offset Manual Finish Date Time Optional Date 24 hr + UTC Offset System Location Conditional Geolocation At least one group of system or manual location parameters must Manual Location Conditional Geolocation be provided. See system and manual location parameters below. System Location Parameters:

5 Parameter Required Data Type Validation and Additional Notes Latitude Mandatory decimal degrees, Longitude Mandatory decimal degrees, Manual Location Parameters: Parameter Required Data Type Validation and Additional Notes Latitude Mandatory decimal degrees, Longitude Mandatory decimal degrees, Catches Parameters: Parameter Required Data Type Validation and Additional Notes Species Code Mandatory Must be a valid ERS species code. Green Weight Estimate Kg Mandatory Number Must be greater than 0. Non Fish or Protected Species Catches Parameters: Parameter Required Data Type Validation and Additional Notes Species Code Mandatory Must be a valid NFPS species code. Validated against the NFPS master data. Seabird Capture Details Conditional Must be provided if 'NFPS' master data property 'is_seabird = true' & 'Fishing Methods' master data property 'require_seabird_capture_details = true'.

6 Parameter Required Data Type Validation and Additional Notes Validated against the Seabird Capture Codes master data. Estimated Weight Kg Conditional Number Must be provided if 'NFPS' master data property 'measured_by = weight' Count Uninjured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count' Count Injured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count' Count Dead Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count' Tag Optional Array of s NFPS Tag Number. Request Body: Example "eventheader": "eventid": "5ba04c30-c81a e-e832da93cf91", "vesselnumber": "123", "isvesselused": true, "notes" : "Fishing conditions were poor", "completeddatetime" : " T12:30:00+13:00", "amendmentreason" : null, "fishingmethodcode": "SJ",

7 "targetspeciescode": "SQU", "mitigationdevicecodes": ["Bird Baffler", "Shouting"], "startlocation": "systemstartdatetime": " T08:00:00+13:00", "systemlocation": "longitude": , "latitude": ,, "manualstartdatetime": " T08:00:00+13:00", "manuallocation": "longitude": , "latitude": ,, "finishlocation": "SystemFinishDateTime": " T12:30:00+13:00", "systemlocation": "longitude": , "latitude": ,, "manualfinishdatetime": " T12:30:00+13:00", "manuallocation": "longitude": ,

8 "latitude": ,, "isnonfishorprotectedspeciescatchpresent": false, "catches": [ "speciescode": "SNA", "greenweightestimatekg": 50.25,, "speciescode": "CRA", "greenweightestimatekg": 23.75, ], "nonfishorprotectedspeciescatches": [ "speciescode": "XAS", "seabirdcapturedetails": "Setting", "estimatedweightkg":, "numberuninjured":, "numberinjured":, "numberdead": 23, "tags": null

9 , ], "deepestluredepthmetres": 55, "bottomdepthmetres": 44, "numberofsinglereels": 677, "numberofdoublereels": 986, 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 Parameters: The response parameters includes all the fields that have been included in the request body and the following additional parameters. Parameter Data Type Validation and Additional Notes Errors Array List of errors, if any. See Errors Parameters below. Errors Parameters: Parameter Data Type Validation and Additional Notes Property Name The name of the property that has an error.

10 Parameter Data Type Validation and Additional Notes Attempted Value The attempted value used. Error Code The type of error. Error Message 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 e-e832da93cf91", "errorcode": "DuplicateValue", "errormessage": "EventId already exists."

11 ]

12 Get Request URL: GET Example: GET Create URL Parameters: Parameter Required Data type Description Client Number Mandatory The main permit holder client number that the event is submitted against. Event ID Mandatory 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, ) Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c b8f ) Authorization: Bearer YOUR_USER_TOKEN Response Response Status: Status Description 200 Ok Status when event has been retrieved successfully.

13 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 Event ID Is Vessel Used Vessel Number Notes Fishing Method Code Data Type Boolean Mitigation Device Codes Target Species Code Start Location See Start Geolocation Set Parameters below. Deepest Lure Depth Metres Bottom Depth Metres Number of Single Reels Number of Double Reels Finish Location See Finish Geolocation Set Parameters below. Array of s Geolocation Set Number Number Number Number Geolocation Set

14 Parameter Is Non Fish Or Protected Species Catch Present Completed Date Time Catches See Catches Parameters below. Non Fish or Protected Species Catches See Non Fish or Protected Species Parameters below. Errors Amendment Reason Data Type Boolean Array of catch Array of NFPS records Array Start Geolocation Set Parameters: Parameter System Location See System Location Parameters below. Manual Location See Manual Location Parameters below. System Start Date Time Manual Start Date Time Data Type Geolocation Geolocation System Location Parameters: Parameter Latitude Longitude Data Type decimal degrees, decimal degrees, Manual Location Parameters:

15 Parameter Latitude Longitude Data Type decimal degrees, decimal degrees, Finish Geolocation Set Parameters: Parameter System Location See System Location Parameters below. Manual Location See Manual Location Parameters below. System Finish Date Time Manual Finish Date Time Data Type Geolocation Geolocation System Location Parameters: Parameter Latitude Longitude Data Type decimal degrees, decimal degrees, Manual Location Parameters: Parameter Latitude Longitude Data Type decimal degrees, decimal degrees,

16 Catches Parameters: Parameter Species Code Green Weight Estimate Kg Data Type Number Non Fish or Protected Species Catches Parameters: Parameter Species Code Seabird Capture Details Estimated Weight Kg Count Uninjured Count Injured Count Dead Tag Data Type Number Number Number Number Array of s Response Body: Example "event": "deepestluredepthmetres": 55, "bottomdepthmetres": 44,

17 "numberofsinglereels": 677, "numberofdoublereels": 986, "method": "SJ", "targetspeciescode": "SQU", "mitigationdevicesused": [ "BIB" ], "startlocation": "systemstartdatetime": " T08:00:00+13:00", "systemlocation": "longitude": , "latitude": ,, "manualstartdatetime": " T08:00:00+13:00", "manuallocation": "longitude": , "latitude": ,, "finishlocation": "systemfinishdatetime": " T12:30:00+13:00", "systemlocation": "longitude": ,

18 "latitude": ,, "manualfinishdatetime": " T12:30:00+13:00", "manuallocation": "longitude": , "latitude": ,, "isnonfishorprotectedspeciescatchpresent": false, "catches": [ "speciescode": "SNA", "greenweightestimatekg": 50.25, "productstate": null, "processedweightkg": null, "numberoffish": null, "speciescode": "CRA", "greenweightestimatekg": 23.75, "productstate": null, "processedweightkg": null, "numberoffish": null

19 , "speciescode": "HOK", "greenweightestimatekg": 23.75, "productstate": null, "processedweightkg": null, "numberoffish": null ], "nonfishorprotectedspeciescatches": [ "speciescode": "XAS", "seabirdcapturedetails": setting, "estimatedweightkg": null, "numberuninjured": null, "numberinjured": null, "numberdead": 23, "tags": null ], "eventid": "JiggingEvent0111p", "schemaedition": 1, "eventversion": 1,

20 "clientnumber": " ", "eventdatetime": " T08:00:00+13:00", "vesselnumber": "1", "isvesselused": true, "notes": "Some notes", "completeddatetime" : " T12:30:00+13:00", "amendmentreason" : null, "errors": []

21 Update Request URL: PUT Example: PUT Create URL Parameters: Parameter Required Data type Description Client Number Mandatory The main permit holder client number that the event is submitted against. Event ID Mandatory 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, ) Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c b8f ) 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 parameters. The amended value of the fields that need to be updated will be passed in the request body.

22 Parameter Required Data Type Description Event Version Mandatory Number The version of the event that the fisher is wanting to update. Request Body: Example "eventheader": "eventid": "5ba04c30-c81a e-e832da93cf91", "vesselnumber": "123", "isvesselused": true, "eventversion": 1, "notes" : "Some notes", "completeddatetime" : null, "amendmentreason" : "Catch reported against incorrect stock.", "fishingmethodcode": "SJ", "targetspeciescode": "SQU", "mitigationdevicecodes": ["Bird Baffler", "Shouting"], "startlocation": "systemstartdatetime": " T08:00:00+13:00", "systemlocation": "longitude": , "latitude": ,,

23 "manualstartdatetime": " T08:00:00+13:00", "manuallocation": "longitude": , "latitude": ,, "finishlocation": "systemfinishdatetime": " T12:30:00+13:00", "systemlocation": "longitude": , "latitude": ,, "manualfinishdatetime": " T12:30:00+13:00", "manuallocation": "longitude": , "latitude": ,, "isnonfishorprotectedspeciescatchpresent": false, "catches": [ "speciescode": "HOK", "greenweightestimatekg": 50.25,

24 , "speciescode": "SNA", "greenweightestimatekg": 23.75, ], "nonfishorprotectedspeciescatches": [], "deepestluredepthmetres": 55, "bottomdepthmetres": 44, "numberofsinglereels": 677, "numberofdoublereels": 986, Response Response Status: Status Description 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 Parameters: The response parameters includes all the fields that have been included in the request body and the following additional parameters.

25 Parameter Data Type Description Errors Array List of errors, if any. See Errors Parameters below. Errors Parameters: Parameter Data Type Description Property Name The name of the property that has an error. Attempted Value The attempted value used. Error Code The type of error. Error Message The description of the error. Example 1: "errors": [] Example 2: "errors": [ "propertyname": "EventVersion", "attemptedvalue": "2",

26 "errorcode": "InvalidValue", "errormessage": "You are not amending the most recent version for this event. Please get the latest version and try again." ]