Welcome to orion-nais’s documentation!

Orion-NAIS

About The Project

Orion-NAIS is a client to work with the NAIS API. It helps with authentication and provides a simple interface to work with the API.

When working with the API you need to have a valid token. The token is valid for a set period of time. The client will automatically refresh the token when it expires.

Why the name Orion?

The NAIS Api is provided through BarentsWatch. BarentsWatch is a Norwegian information portal that provides overview of activity and knowledge in coastal and sea areas. The Norwegian movie “Orion’s Belt” from 1985 is an action movie set in the Barents region. About three men, a bulldozer, a Russian helicopter and a ship. Thus the name Orion.

Installation

Requires Python 3.10 or later.

pip install orion-nais

or using pipenv:

pipenv install orion-nais

or using poetry:

poetry add orion-nais

Usage

To install the package in your project run

poetry add orion-nais

then add an .env file to your project with the following variables:

CLIENT_ID=
CLIENT_SECRET=

If you don’t have a client id and secret you can get one from your BarentsWatch account.

Then you can use the client like this:

from orion import Orion

orion = Orion()
# Get the last 24 hours of AIS data for a ship with MMSI XXXXXXXXXX
ais = orion.get_ais_last_24H(SHIP_MMSI)
# Convert the AIS data to a line
line = orion.ais_to_line(ais)

Local development

Requirements

pyenv - manage python versions
poetry - manage python dependencies

To install on mac you can use homebrew:

brew upgrade
brew install pyenv

You can either install poetry with homebrew or the way described in the documentation

Makefile commands

make lint
- lint the code in the src folder with black, isort and flake8. Mypy will check for correct typing.
make format
- format the code in the src folder with black and isort.
make test
- run the tests in the tests folder.
make bump-patch
- bump the patch version of the package. Example: 0.1.0 -> 0.1.1
make bump-minor
- bump the minor version of the package. Example: 0.1.0 -> 0.2.0
make bump-major
- bump the major version of the package. Example: 0.1.0 -> 1.0.0
make release
- publish the package to pypi. You need to have an account and be logged in to pypi.

Structure

.
├── .bumpversion.cfg
├── .editorconfig
├── .flake8
├── .gitignore
├── Makefile
├── README.md
├── orion
│   ├── client.py
│   ├── mmsi.py
│   ├── types
│   │   └── ais.py
│   ├── urls.py
│   ├── utils
│   │   └── get_data.py
│   └── vessel_codes.py
├── poetry.lock
├── pyproject.toml
└── tests
    ├── make_mock_data.py
    ├── mocks
    └── test_orion.py

.bumpversion.cfg
- Configuration file for bumpversion.
.editorconfig
- Configuration file for editorconfig.
.flake8
- Configuration file for flake8.
.gitignore
- Configuration file for git.
pyproject.toml
- Configuration file for poetry. Mypy and isort is configured here.
poetry.lock
- Lock file for poetry.
Makefile
- Makefile for the project. Here you can find commands for linting and formatting.
README.md
- This file.
orion
- The source code for the package.
- client.py
  - The client class.
- mmsi.py
  - A dataclass for handling MMSI numbers and MID-codes (jurisdiction).
- types
  - A folder for types.
  - ais.py
    - A class for handling AIS messages.
- urls.py
  - A file with urls for the API.
- utils
  - A folder for utility functions.
  - get_data.py
    - A function for getting data from other sources. Not used by the Orion client. Contains code for getting data from the Norwegian Petroleum Directorate.
- vessel_codes.py
  - A dataclass for looking up vessel codes.
tests
- Tests for the package.

Contributing

Do you have write permissions to the repo? Then you can clone this project to a folder on your computer.

git clone https://github.com/BergensTidende/orion-nais.git

If not do the following:

Create a personal fork of the project on Github.
Clone the fork on your local machine. Your remote repo on Github is called origin.
Add the original repository as a remote called upstream.
If you created your fork a while ago be sure to pull upstream changes into your local repository.

This will clone the repo into orion-nais.

Create a branch for your changes

git checkout -b name-of-branch

Make your changes, rememeber to commit. And always write your commit messages in the present tense. Your commit message should describe what the commit, when applied, does to the code – not what you did to the code.

If you’re working on a clone push the branch to github and make PR.

If your’re working a fork:

Squash your commits into a single commit with git’s interactive rebase. Create a new branch if necessary.
Push your branch to your fork on Github, the remote origin.
From your fork open a pull request in the correct branch. Target the project’s develop branch if there is one, else go for master.
If the maintainer requests further changes just push them to your branch. The PR will be updated automatically.
Once the pull request is approved and merged you can pull the changes from upstream to your local repo and delete your extra branch(es).

Contact

Bord4 - bord4@bt.no

API reference

class orion.client.Orion(client_id=None, client_secret=None, skip_auth=False)[source]

Interface to Barentswatch API

The CLIENT_ID and CLIENT_SECRET should be exposed as environment variables called CLIENT_ID and CLIENT_SECRET or passed as parameters when creating an instance of the class.

orion = Orion(client_id=”myclientid”, client_secret=”myclientsecret”)

Parameters:

client_id (Optional[str]) – id for your user at Barentswatch. Use if not set in .env file.
client_secret (Optional[str]) – secret for your user at Barentswatch. Use if not set in .env file.
skip_auth (Optional[bool]) – skip authentication. Useful for testing.

add_jurisdiction_and_ship_type(ais)[source]

Adds the jurisdiction and ship type to the dataframe

Parameters:: ais (List[Ais]) – the ais track from NAIS
Return type:: List[Ais]

ais_to_line(ais, simplify=None)[source]

Creates a line for all the points in the ais json

Parameters:

ais (Dict[str, object]) – ais json
simplify (int, optional) – simplify the line, threshold given in meter. Defaults to None.

Returns:

dataframe with one line

Return type:

GeoDataFrame

auth(request)[source]

Set the authentication token on every request

Return type:: Request
Parameters:: request (Union[Request, PreparedRequest]) –

authenticate()[source]

Authenticate with Barentswatch

Return type:: None

buffer_around_gdf(gpd, distance, column=None)[source]

Create a buffer around a geopandas dataframe

Parameters:

gpd (geopandas) – geopandas dataframe
distance (int) – distance in meters
column (Optional[str]) –

Returns:

geopands dataframe with buffer

Return type:

geopandas

buffer_around_point(lat, lon, distance)[source]

Create a buffer around a point

Parameters:

lat (float) – latitude
lon (float) – longitude
distance (int) – distance in meters

Returns:

GeoJSON geometry

Return type:

str

calculate_radius_in_meters_from_km2(area)[source]

Calculate the radius of a circle with a given area

Parameters:: area (float) – area of the circle in km^2
Returns:: radius in meters
Return type:: float

explore(_gdf)[source]

helper function to geopandas explore

Parameters:: _gdf (GeoDataFrame) – the geodataframe to explore
Returns:: an interactive map of our data
Return type:: html

get_ais(mmsi, fromDate, toDate)[source]

Get AIS for a ship in a give timeframe

Parameters:

mmsi (int) – Maritime Mobile Service Identity (MMSI) is used as an uinique identifer for a ship
fromDate (str) – start of timeframe example: 2021-07-21T00:00:00Z
toDate (str) – end of timeframe example: 2021-07-23T18:00:00Z

Returns:

json of ais track

Return type:

json

get_ais_last_24H(mmsi)[source]

Get AIS for a ship last 24 hour

Parameters:

mmsi (int) – Maritime Mobile Service Identity (MMSI) is used as
ship (an uinique identifer for a) –

Returns:

json of ais track

Return type:

json

get_mmsis_in_area(geometry, from_date=None, to_date=None)[source]

Get AIS for ships in given area inside the timeframe

Parameters:

geometry (Dict[str, object]) – GeoJSON geometry
from_date (datetime, optional) – The start of the timeframe, if not given the function will get last 24H. Defaults to None.
to_date (datetime, optional) – The end of the timeframe, if not given the function will get last 24H. Defaults to None.

Return type:

List[Dict[str, object]]

get_mmsis_in_area_around_point(lat, lon, distance, from_date=None, to_date=None)[source]

Get AIS data from ships inside the geometry in a give timeframe

Parameters:

lat (float) – latitude
lon (float) – longitude
distance (int) – distance in meters
from_date (str, optional) – The start of the timeframe, if not given the function will get last 24H. Defaults to None.
to_date (str, optional) – The end of the timeframe, if not given the function will get last 24H. Defaults to None.

Returns:

Json of combined AIS tracks

Return type:

Array

get_multiple_ais(mmsis, fromDate=None, toDate=None)[source]

Get AIS data from multiple ships in a give timeframe

Parameters:

mmsis (Array(int)) – An array of MMSIs
fromDate (datetime, optional) – The start of the timeframe, if not given the function will get last 24H. Defaults to None.
toDate (_type_, optional) – The end of the timeframe, if not given the function will get last 24H. Defaults to None.

Returns:

Json of combined AIS tracks

Return type:

Array

json_to_gdf(_json)[source]

Transforms a json response from NAIS to a GeoDataFrame

Parameters:: _json ([dict]) – array of dicts, json response from NAIS
Returns:: a GeoDataFrame with geometry column and crs
Return type:: GeoDataFrame

merge_points_to_line(_gdf, simplify=None)[source]

Creates a line for all the points in the geodataframe

Parameters:

_gdf (GeoDataFrame) – the gdf with all the points
simplify (Optional[int]) –

Returns:

dataframe with one line

Return type:

GeoSeries

class orion.mmsi.Jurisdiction(name, midcode, full_name)[source]

Represents a jurisdiction. A jurisdiction is a country or a group of countries

Parameters:

name (str) –
midcode (str) –
full_name (str) –

class orion.mmsi.Mmsi(jurisdictions=<factory>)[source]

Used for working with MMSI numbers. MMSI numbers are used to identify ships. Has utility methods for checking if a MMSI is a ship and getting the MID code for a ship. Also for filtering on country codes.

Parameters:: jurisdictions (List[Jurisdiction]) –

get_jurisdiction(mmsi)[source]

Get the jurisdiction of a ship.

Parameters:: mmsi (int) – mmsi number
Returns:: Jurisdiction code
Return type:: str

get_jurisdiction_name(mmsi)[source]

Get the jurisdiction name of a ship.

Parameters:: mmsi (int) – mmsi number
Returns:: Jurisdiction name
Return type:: str

get_mid(mmsi)[source]

If MMSI is a ship, return the MID code.

Parameters:: mmsi (int) – mmsi number
Raises:: ValueError – If the mmsi is not a ship, raise ValueError
Returns:: MID code
Return type:: str

is_norwegian(mmsi)[source]

Check if a ship is Norwegian.

Parameters:: mmsi (int) – mmsi number
Returns:: True if Norwegian, False otherwise
Return type:: bool

is_valid_ship_mmsi(mmsi)[source]

check if mmsi is a ship.

Parameters:: mmsi (int) – mmsi number
Returns:: True if mmsi is a ship, False otherwise
Return type:: bool

remove_norwegian_gdf(gdf)[source]

Removes all Norwegian ships from a dataframe.

Parameters:

df (panda.DataFrane) – _description_
gdf (GeoDataFrame) –

Returns:

_description_

Return type:

_type_

remove_norwegian_list(ships)[source]

Removes all Norwegian ships from a list.

Parameters:: ships (List) – A list of ships
Returns:: A list of ships without Norwegian ships
Return type:: List

class orion.vessel_codes.AisVesselCode(name, fromCode, toCode, description)[source]

Represents a vessel type code. A vessel code is a number that represents a type of vessel. Either as a single number or a range of numbers. Example: Vesel code 51 is a Search and Rescue vessel

Parameters:

name (str) –
fromCode (int) –
toCode (int) –
description (str) –

class orion.vessel_codes.AisVesselCodes(codes=<factory>)[source]

Class to look up vessel codes and different utility functions for vessel codes.

Parameters:: codes (List[AisVesselCode]) –

get_vessel_codes(vessel_type)[source]

Find codes for a vessel type

Parameters:: vessel_type (str) – The name of the vessel type we are searching for
Returns:: a list of codes for the vessel type
Return type:: List[AisVesselCode]

get_vessel_codes_from_description(vessel_description)[source]

Find codes for a vessel type

Parameters:: vessel_description (str) – The description of the vessel type we are searching for
Returns:: a list of codes for the vessel type
Return type:: List[AisVesselCode]

get_vessel_type(code)[source]

Find a vessel type by code

Parameters:: code (int) – the vessel code to search for
Returns:: the vessel type if found, otherwise None
Return type:: Optional[AisVesselCode]

get_vessel_type_description(code)[source]

Find a vessel type by code

Parameters:: code (int) – the vessel code to search for
Returns:: the vessel type if found, otherwise None
Return type:: Optional[AisVesselCode]

get_vessel_type_name(code)[source]

Find a vessel type by code

Parameters:: code (int) – the vessel code to search for
Returns:: the vessel type if found, otherwise None
Return type:: Optional[AisVesselCode]

orion.utils.get_data.get_oil_installations()[source]

get all the oil installations in Norwegian waters

Returns:: geodataframe with all the oil installations
Return type:: geopandas.GeoDataFrame

orion.utils.get_data.get_oil_rigs()[source]

Get all the oil rigs in Norwgian waters

Returns:: Gepandas dataframe with all the oil rigs
Return type:: geopandas.GeoDataFrame

orion.types.ais: alias of <module ‘orion.types.ais’ from ‘/home/docs/checkouts/readthedocs.org/user_builds/orion-nais/checkouts/latest/orion/types/ais.py’>

Welcome to orion-nais’s documentation!

Orion-NAIS

Table of Contents

About The Project

Why the name Orion?

Installation

Usage

Local development

Requirements

Makefile commands

Structure

Contributing

Contact

API reference