Ports & Navigation API

Ports & navigation infrastructure

Query port location data, identifiers, and geographic coordinates for ports, terminals, and anchorages worldwide. Port records are updated daily at 06:00 UTC.

Global Port Coverage

The ports database provides reference information for maritime ports around the world. Each port entry includes its official UN/LOCODE identifier, geographic coordinates, country, and descriptive name. This data supports routing, logistics planning, and integration with other maritime systems.

Use the Ports API to look up port details by UN/LOCODE, search for ports by name, or find ports within a specific geographic area. Combined with the Port Events API, you can build port monitoring and logistics applications.

Database Coverage: The database includes major commercial ports, container terminals, bulk terminals, passenger ports, and smaller harbors across all continents and major shipping regions.

Understanding UN/LOCODE

The UN/LOCODE (United Nations Code for Trade and Transport Locations) is the international standard for identifying ports and other transport locations. It's maintained by UNECE and used globally in shipping documentation, customs declarations, and logistics systems.

Code Structure

Country

RTM

Location

NLRTM

Rotterdam

The first two characters are the ISO 3166-1 country code. The remaining three characters identify the specific location within that country.

Major Port Examples

CNSHA

Shanghai, China

SGSIN

Singapore

NLRTM

Rotterdam, Netherlands

KRPUS

Busan, South Korea

DEHAM

Hamburg, Germany

USNYC

New York, USA

AEJEA

Jebel Ali, UAE

GBFXT

Felixstowe, UK

Use Cases

Route Planning

Look up port coordinates for voyage planning and distance calculations. Find alternative ports along shipping routes.

Data Enrichment

Enrich shipping data with port names and locations. Convert UN/LOCODE values to human-readable information.

Geographic Search

Find ports in specific regions or near particular coordinates. Useful for map-based applications.

Autocomplete Systems

Build port search and selection interfaces with name-based search and autocomplete functionality.

Available Endpoints

GET /port/{unlocode}

Get Port by UN/LOCODE

Retrieve detailed information about a specific port using its UN/LOCODE identifier. Returns port name, country, coordinates, and additional metadata.

Parameters:

unlocode - Port UN/LOCODE (e.g., NLRTM, SGSIN)

GET /search/ports

Search Ports

Search for ports by name, country, type, size, region, or harbor characteristics. Supports partial matching for autocomplete-style functionality. Returns a paginated list of matching ports.

Parameters:

filter.name - Port name to search (partial match)
filter.country - ISO 2-letter country code or country name; repeatable, matches if any value matches
filter.type - Port type classification (case-insensitive); repeatable, matches if any value matches. Accepted values: Port, Seaport, River Port, Lake Port, Dry Port, Offshore Terminal; any other value returns HTTP 400
filter.size - Port size classification
filter.region - Geographic region name (partial match)
filter.harborSize - Harbor size classification
filter.harborUse - Primary harbor use
pagination.limit - Results per page (max 50, default 20)
pagination.nextToken - Cursor for next page of results

At least one filter parameter is required.

To pass multiple values for a repeatable filter, repeat the parameter itself (e.g. ?filter.type=Seaport&filter.type=River+Port); comma-separated values are not supported.

GET /location/ports/bounding-box

Ports in Bounding Box

Find all ports within a rectangular geographic area. Perfect for map applications showing ports in the visible viewport. Maximum total span of 4 degrees (|latTop - latBottom| + |lonRight - lonLeft| ≤ 4).

Parameters:

filter.latBottom, filter.latTop - Latitude bounds
filter.lonLeft, filter.lonRight - Longitude bounds
pagination.limit - Results per page (max 50, default 20)
pagination.nextToken - Cursor for next page of results

GET /location/ports/radius

Ports Within Radius

Find all ports within a specified distance from a center point. Useful for finding nearby alternative ports or ports along a route.

Parameters:

filter.latitude - Center point latitude
filter.longitude - Center point longitude
filter.radius - Search radius in meters (required, max 100,000)
pagination.limit - Results per page (max 50, default 20)
pagination.nextToken - Cursor for next page of results

Navigation Infrastructure

Lighthouses, radio beacons, DGPS stations, and MODUs. Pass the aid type as {type} (lightaids, radiobeacons, dgps, modus) to the endpoints below.

Endpoint Pattern: Each infrastructure type follows the same pattern with search and location-based endpoints. For search, replace {type} with: lightaids, radiobeacons, dgps, or modus. For location queries, use: lightaids, radiobeacons, dgps, or modu.

GET /search/{type}

Search Navigation Aids

Search for navigation infrastructure by name. Returns a paginated list of matching results with full details.

Parameters:

filter.name - Name to search for (required)
pagination.limit - Results per page (max 50, default 20)
pagination.nextToken - Cursor for next page of results

Available Endpoints:

/search/lightaids - Search lighthouses and light aids
/search/radiobeacons - Search radio beacons
/search/dgps - Search DGPS stations
/search/modus - Search offshore drilling units

GET /location/{type}/bounding-box

Find in Bounding Box

Find all navigation aids within a rectangular geographic area. Ideal for map displays showing aids in the current viewport. Maximum total span of 4 degrees (|latTop - latBottom| + |lonRight - lonLeft| ≤ 4).

Parameters:

filter.latBottom, filter.latTop - Latitude bounds
filter.lonLeft, filter.lonRight - Longitude bounds
pagination.limit - Results per page (max 50, default 20)
pagination.nextToken - Cursor for next page of results

GET /location/{type}/radius

Find Within Radius

Find all navigation aids within a specified distance from a center point. Useful for identifying aids near a vessel's position or along a route.

Parameters:

filter.latitude - Center point latitude
filter.longitude - Center point longitude
filter.radius - Search radius in meters (required, max 100,000)
pagination.limit - Results per page (max 50, default 20)
pagination.nextToken - Cursor for next page of results

Code Examples

Get Port Details (cURL)

curl -X GET "https://api.vesselapi.com/v1/port/NLRTM" \
     -H "Authorization: Bearer YOUR_API_KEY"

Search Ports by Name (Python)

import requests

response = requests.get(
    "https://api.vesselapi.com/v1/search/ports",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"filter.name": "Rotterdam", "pagination.limit": 20}
)

ports = response.json()
for port in ports["ports"]:
    print(f"{port['name']} ({port['unlo_code']}) - {port['country']['name']}")

Find Nearby Ports (JavaScript)

// Find ports within 50km of current position
async function findNearbyPorts(lat, lon, radiusMeters = 50000) {
  const response = await fetch(
    `https://api.vesselapi.com/v1/location/ports/radius?` +
    new URLSearchParams({
      "filter.latitude": lat,
      "filter.longitude": lon,
      "filter.radius": radiusMeters
    }),
    { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
  );

  const data = await response.json();
  return data.ports;
}

// Example: Find ports near Singapore
const nearbyPorts = await findNearbyPorts(1.3521, 103.8198);
console.log(`Found ${nearbyPorts.length} ports nearby`);

Response Fields

Field	Description	Example
unlo_code	UN/LOCODE identifier	NLRTM
name	Port name	Rotterdam
country.code	ISO 2-letter country code	NL
country.name	Full country name	Netherlands
latitude	Port latitude (WGS84)	51.9225
longitude	Port longitude (WGS84)	4.4792
region_name	Geographic region where the port is located	Southeast Asia
type	Port classification type	Seaport
size	Size classification of the port	Large
harbor_size	Harbor size classification	Large
harbor_type	Type of harbor (CB=Coastal Breakwater, CN=Coastal Natural, etc.)	CN
channel_depth	Depth of the approach channel	24.0
max_vessel_length	Maximum length of vessel that can be accommodated	400.0
pilotage_compulsory	Whether pilotage is mandatory for vessel entry	true
tugs_available	Whether tug services are available	true
shelter	Quality of shelter from weather	Good

Additional fields such as anchorage_depth, max_vessel_beam, max_vessel_draft, supply_water, medical_facilities, and more are also available. See the API Explorer for the complete schema.

Navigation Infrastructure Fields

Light Aids

Field	Description
name	Name of the light aid
feature_number	NGA feature number identifier
characteristic	Light flash pattern description (e.g., Fl W 7.5s)
range	Nominal range of light in nautical miles
structure	Description of the physical structure
height_feet_meters	Height of light above water in feet and meters
position	Human-readable position description
geopolitical_heading	Country or major geographic area
location	GeoJSON point for geospatial queries

DGPS Stations

Field	Description
name	Station name
station_id	Station identifier code
frequency	Broadcast frequency in kHz
range	Signal range in nautical miles
transfer_rate	Data transfer rate in bits per second
position	Human-readable position description
geopolitical_heading	Country or major geographic area
location	GeoJSON point for geospatial queries

Radio Beacons

Field	Description
name	Name of the radio beacon
frequency	Broadcast frequency
characteristic	Beacon transmission characteristic
range	Signal range in nautical miles
sequence_text	Transmission sequence description
position	Human-readable position description
geopolitical_heading	Country or major geographic area
location	GeoJSON point for geospatial queries

The tables below show the most commonly used fields. Additional fields are available in each response. See the API Explorer for the complete schemas.

Mobile Offshore Drilling Units (MODUs)

Field	Description
name	Name of the drilling unit
rig_status	Current operational status of the rig
date	Date of the position report
latitude	Geographic latitude in decimal degrees
longitude	Geographic longitude in decimal degrees
navigation_area	NAVAREA designation
distance	Distance from reference point in nautical miles
location	GeoJSON point for geospatial queries

Explore the Ports Database

Try these endpoints interactively in the API Explorer.

Open API Explorer Get Your API Key

Ports & Navigation API

Global Port Coverage

Understanding UN/LOCODE

Code Structure

Major Port Examples

Use Cases

Route Planning

Data Enrichment

Geographic Search

Autocomplete Systems

Available Endpoints

Get Port by UN/LOCODE

Search Ports

Ports in Bounding Box

Ports Within Radius

Navigation Infrastructure

Search Navigation Aids

Find in Bounding Box

Find Within Radius

Code Examples

Get Port Details (cURL)

Search Ports by Name (Python)

Find Nearby Ports (JavaScript)

Response Fields

Navigation Infrastructure Fields

Light Aids

DGPS Stations

Radio Beacons

Mobile Offshore Drilling Units (MODUs)

Explore the Ports Database

Related Documentation

Port Events

Vessel Tracking