Navapi API Documentation
1. Introduction to Navapi APIs:
1.1. Navapi Products Overview:
We wish to welcome you to the Documentation page of Navapi products. NavAPI offers you a suite of API products, enabling your systems to interact with all, or any of the APIs listed below, depending on your subscription(s) and/or purchased tokens:
 | AISP | AIS Positions API |
 | SRTG | Sea Routing API |
 | WTHR | Global Weather API |
 | GHGE | GHG Emissions API |
 | GEOC | Geocoding API |
 | MAPS | Marine Maps API |
1.2 API products description:
By API Products we mean the umbrella name of each of our APIs. This said, each API product, consists of the relevant API end-points, and each API endpoint provides the API functionality it is meant to provide you with. Below, we list our current API services along with a brief description for each one.
The AIS Positions API product (AISP): The AIS Positions API, allows your systems to access comprehensive ship tracking and monitoring data with full global coverage, through the vessels’ Automatic Identification Systems (AIS). This service delivers both real-time and historical data concerning ship positions, movements, and statuses, and in addition tracks ships by destination-ETA, or radius from any given coordinates.
The Sea Routing API product (SRTG): The Sea Routing API, allows your system to interact with our routing engines, and calculate on the fly sea routes and distances, between any port and/or coordinate across the globe; the service gives users options to adjust various navigational parameters, such as pirate zones, SECA zones, ASL lanes, Great Circle versus Rhumbline navigation methods etc., as well as to simultaneously calculate many alternative routes through given Routing Points so as to find optimal routes and sequences, plus calculate each SECA travel segment separately.
The Global Weather API product (WTHR): The Global Weather API, offers point and area data with global coverage of sea-land-air surface levels, for 65 weather variables and for an up to 10 days forecast. Other than point weather data, this service also offers astro data with various positions and phases of the sun and the moon. This service will soon be enriched with more features such as tides data, meteograms, and weather maps, so as users will be able to get ready-made rendered weather information and present them in their applications as a white labelled product.
The GHG Emissions API product (GHGE): The Green House Gas Emissions API, complies with the standards of the environmental reporting and suits a wide range of application within the shipping and the logistics sectors. This service, facilitate users to calculate in detail CO₂ and Green House Gas emissions, based on all voyage variables, such as traveling times, Port-Canal waiting times, Port working times, fuel/bunker consumptions etc. Soon more features will be added, such as Activity based Emissions Calculations, Container (FCL/LCL) CO2 calculations, and EU allowances APIs.
The Geocoding API product (GEOC): The “Geocoding API” provides a complete sea ports database, so as users find any port-POI-terminal across the globe. The API can also inform the user whether the entered location falls within designated areas, including the following:
- SECA area
- Piracy area-
- HRA-JWLA area-
- ERZ etc.
- Load Line Zone
- Country-Trade area
- Time Zone-Sea Area
- Energy Index Area
- Feeder Service Area and more.
Soon the service will be enriched with more sub-services/endpoints, offering information for airports, land places and many more.
The Marine Maps API product (MAPS): The Maps API enable users to integrate maritime maps into their applications or websites. It is offered as a Tile Map Service (TMS), and provides the following Maps and Map Layers:
- Five world maps, that you can use as basemaps
- SECA areas map layer
- JWLA areas (War Listed Areas)
- Ports map layers, that can be added on top of any basemap and show all ports of the world
- MARPOL areas
- VRA areas (Voluntary Reporting Areas)
- INL areas (International Navigating Limits)
- Nordic Plan navigating limits
- HRA (High Risk Areas)
- Time Zones
- Load Line Zones
- Piracy Areas
- Archipelagic Sea Lanes
- US Captain of the port areas
1.3. API Endpoints:
API Endpoint: By API Endpoint, we mean the specific Endpoint, belonging to, and functioning under each API product, as those products explained under §1.1. Instructions on how each API works, example API Requests, example API responses, parameterizations etc. for each endpoint, will be found under each Endpoint’s section of this documentation. Below we list all Endpoints, along with a short description for each one of them.
| Service | Endpoint | Short description |
|---|---|---|
| AISP | /aisp/autc/ShipSearch | Finds a vessel by IMO, MMSI, or name [Autocomplete] |
| AISP | /aisp/svsl/LastPosition | Returns a single vessel’s last updated position |
| AISP | /aisp/mvsl/LastPositions | Returns multiple vessels’ last updated positions |
| AISP | /aisp/svsl/HistoricalTracks | Returns a single vessel’s historical tracks |
| AISP | /aisp/mvsl/WithinRange | Returns all vessels within a specified radius from any given coordinate |
| AISP | /aisp/mvsl/FindByDestination | Returns all vessels heading to any specified destination |
| SRTG | /srtg/calc/SingleRoute | Calculates the sea route between two points/ports at sea (A to B) |
| SRTG | /srtg/calc/MultipleRoutes | Calculates multiple sea routes (up to 16 legs in a single API call) |
| SRTG | /srtg/calc/AlternativeRoutes | Calculates multiple sea routes through any specified routing points |
| SRTG | /srtg/calc/SecaSegements | Calculates separately all SECA segments from a series of waypoints |
| WTHR | /wthr/list/ForecastModels | Returns a list of all available weather models |
| WTHR | /wthr/list/WeatherVariables | Returns a list of available weather variables (per model) |
| WTHR | /wthr/list/Timesteps | Returns a list of all available timesteps (per model) |
| WTHR | /wthr/svar/NearestValue | Returns the non-interpolated forecast’s nearest grid values for any given coordinate |
| WTHR | /wthr/svar/AreaForecast | Returns a single weather variable’s values for any specified area |
| WTHR | /wthr/svar/PointForecsat | Returns a single weather variable’s value for any specified timestep and coordinate |
| WTHR | /wthr/mvar/PointForecast | Returns multiple weather variables’ values for various timesteps for any coordinate |
| WTHR | /wthr/calc/AstroData | Returns various timings and positions of the sun and the moon |
| GHGE | /ghge/engb/SeaTravel | Calculates energy-based emissions for any specified sea travel |
| GHGE | /ghge/engb/SeaVoyage | Calculates energy-based emissions for an entire voyage |
| GEOC | /geoc/autc/PortSearch | Finds any sea port in the world [Autocomplete] |
| GEOC | /geoc/info/SeaPoints | Returns essential information for any specified point at sea |
| MAPS | /maps/mapname/apikey | Integrates NavAPI maps into any map Library |
1.4. Custom Base URLs and/or Endpoint:
Our services technology: All our services are using advanced technology with failover, load balancing and smart network routing, in order to ensure fast, smooth and uninterrupted services for all of our APIs. Depending on the usage scenario and the case, Navapi, either through the user dashboard or by email, will provide users with the relevant base URLs and may also ask you to use customized endpoints, not listed in this documentation, depending on factors such as:
- If you use a trial account, a dev account, or a production/paid account.
- If you have subscribed to an unlimited plan, where in such case you will have dedicated infrastructure.
- If we created a custom API for you, tailor-made to your needs as per specifications signed under a SoW.
- If you are a known customer, and you agreed/wish to test a new product in beta.
- If we agreed to advance your paid account to a new API version, not publicly released yet.
- If your account violated out Terms of Service, and after assessing the events and logs, we decided to direct your account to a sandboxed service.
2. Authentication
2.1. Obtaining an API key:
You will need an API key to get started and use any of our services. If you are a new user:
- Either contact us by sending an email from a business email account to our support ,
- or sign up, again by using a business email, by clicking on the Sign-Up button on the top right of our website, and follow the registration process.
- If you have already registered on our website, click on the Log in button on the top right of our website and Login.
- Once you Log in to the dashboard, you will be able to create Trial API keys for most of our products, by clicking on the “+ Create Trial APIs”.
2.2. Authentication:
We use a Bearer token Authorization for all the Endpoints (APIs), except the MAPS service, which uses a basic key authorization. The Bearer token (api key) will be given to you as explained under §3.1.
2.3. How to use a Bearer Token:
To add your API key, under Authorization, select the Bearer token authentication method; then add your key to the relevant field, as shown below:
Alternatively, you can add the Bearer Token Authorization key, strait to the Headers of the call; in such case, you should use the word “Bearer” before the token, as in the below example:
2.4. MAPS service-API key:
The NavAPI maps, are offered as a TMS (Tile Map Service) and as a result the authorization method is by adding your API key straight into the Api call URL (TMS URL), as below:
Request TMS URL format:
https://{{Base URL}}/{{Endpoint}}/API-key/{z}/{x}/{y}.pngBelow is an example on how to add a TMS URL in QGIS: