Skip to main content

Example requests - FiskInfo Reporting API

Here are a few example requests for the FiskInfo Reporting API.

To get the appropriate permissions for your client to use device flow you have to contact us by mail.

Reporting requests​

1. Get profile​

curl 'https://www.barentswatch.no/bwapi/v3/geodata/fishingfacilityprofile' \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: bearer <access_token>'
Example response
{
  "haveProfile": true,
  "haveDownloadRights": true,
  "contactPersonDetail": {
    "id": "string",
    "firstName": "Ola ",
    "lastName": " Nordmann",
    "phoneNumber": "98990099",
    "email": "ola.nordmann@example.com"
  },
  "vesselInfo": {
    "vesselId": "baeeb81b-85d1-4303-9cfa-6ceaba72793d",
    "mmsi": 257001000,
    "imo": 9144081,
    "ircs": "LAMA",
    "regNum": "N-238-Ø",
    "sbrRegNum": null,
    "vesselName": "Havbris",
    "vesselPhone": "20990099",
    "vesselEmail": "string"
  }
}

This gets the FiskInfo profle of the logged in user. "haveDownloadRights" must be true to get extended info about fishingfacilities.

"haveProfile" must be true to send reports. The user can only send reports for the vessel in the profile.

2. Get reports and tools for the user​

curl 'https://www.barentswatch.no/bwapi/v3/geodata/fishingfacilitychanges' \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: bearer <access_token>'

The user may use several devices to access the same data. For example the barentswatch.no/fiskinfo website, the Sintef Fiskinfo app, and a chart plotter. This endpoint lists all tools and any pending reports.

Confirmed tools: This is tools that have been confirmed, and are visible to all who download the fishingfacilities dataset.

Pending reports: Reports that that are waiting to be confirmed.

Failed reports: Reports that were not sent to KVS because they failed. This should normally not happen.

3. Report a tool as retrieved​

This should be one of the tools from confirmed_tools list from the fishingfacilitychanges-endpoint:

curl 'https://www.barentswatch.no/bwapi/v3/geodata/fishingfacilitychange/retrieved'
-H 'Accept: application/json, text/plain, */*' \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Authorization: bearer <token>' \
--data-raw '{"toolId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","removeddatetime":"2020-09-22T12:15:49.641Z"}'

After sending a report, the client should refresh the data from the fishingfacilitychanges-endpoint.

4. Report a new tool as deployed​

To report a new tool as deployed:

curl 'https://www.barentswatch.no/bwapi/v3/geodata/fishingfacilitychange/deployed' \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Authorization: bearer <token>' \
--data-raw '{
  "toolTypeCode": "NETS",
  "geometry": {"type":"Point","coordinates":[30,10]},
  "setupTime": "2021-12-13T09:49:56.607Z",
  "toolCount": 15
}'

After sending a report, the client should refresh the dta from the fishingfacilitychanges-endpoint.

Device login​

Login with a client that is set up with device flow.

1. Start login​

When a user wants to log in, the device should make a request to the deviceauthorization endpoint:

curl --location --request POST 'https://id.barentswatch.no/connect/deviceauthorization' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=MyClientId' \
--data-urlencode 'scope=api offline_access'
Response
{
"device_code": "HuF-7KISrXG0huI-RoqVdnba9d92zzn3hkEuN86hNeg",
"user_code": "788578139",
"verification_uri": "https://id.barentswatch.no/device",
"verification_uri_complete": "https://id.barentswatch.no/device?userCode=788578139",
"expires_in": 3600,
"interval": 5
}

The user_code is the code the user must enter to complete the login. This code must be displayed to the user, with instructions to go to the verification_uri and enter the code. The verification_uri_complete could be encoded as a QR-code and displayed to the user on the device.

expires_in (seconds) is the time until user_code and device_code expires. If they expire the process has to be restarted.

interval (seconds) is the shortest interval that the device can poll the token endpoint.

2. Poll for token​

Now the device can poll every 5 seconds (the interval value) for the token:

curl --location --request POST 'https://id.barentswatch.no/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=MyClientId' \
--data-urlencode 'device_code=HuF-7KISrXG0huI-RoqVdnba9d92zzn3hkEuN86hNeg' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code'

While waiting for the user to enter the user_code, the response will be:

{
    "error": "authorization_pending"
}

If the user does not enter the user_code, or the device does not pull for token within the expire interval, the process must be restarted, The response will be:

{
    "error": "expired_token"
}

When the user grants access, the response will be:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZ5l8VuQGDQGCSG1YAK01d_slyBWnrYohhRFj6wY9GwVXxF7kTadpJlaE",
    "expires_in": 3600,
    "token_type": "Bearer",
    "refresh_token": "y255GMDNpgn12345UiNQkAYd1cZL-sqmfhjM7xS9bGY",
    "scope": "api offline_access"
}

The access_token is used in the authorization header as bearer token when the device is making requests to the api.

The refresh_token must be stored with the device and updated every time it is being used. The refresh_token is used to get a new access_token. The refresh_token can only be used once. You get a new refresh_token at the same time you request a new access_token. The refresh_token has an expiration time of TBD.

Expires_in (seconds) is expiration time for the access_token (1 hour).

Refresh tokens​

When the access token expires, the tokens can be refreshed using the refresh_token:

curl --location --request POST 'https://id.barentswatch.no/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'refresh_token=y255GMDNpgn12345UiNQkAYd1cZL-sqmfhjM7xS9bGY' \
--data-urlencode 'client_id=MyClientId' \
--data-urlencode 'grant_type=refresh_token'
Response
{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZ5l8VuQGDQGCSG1YAK01d_slyBWnrYohhRFj6wY9GwVXxF7kTadpJlaE",
    "expires_in": 3600,
    "token_type": "Bearer",
    "refresh_token": "SH2bboSkkRPAOkY19627TChzBwdNRvALyen_psqJw7U",
    "scope": "api offline_access"
}

The access_token is used in the authorization header as bearer token when the device is making requests to the api.

The new refresh_token must be stored with the device and replaces the refresh_token used to perform the request. The old refresh_token is no longer valid.