Ports Database API
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
Location
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
/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)
/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 namefilter.type- Port type classification (case-insensitive)filter.size- Port size classificationfilter.region- Geographic region name (partial match)filter.harborSize- Harbor size classificationfilter.harborUse- Primary harbor usepagination.limit- Results per page (max 50, default 20)pagination.nextToken- Cursor for next page of results
At least one filter parameter is required.
/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 boundsfilter.lonLeft,filter.lonRight- Longitude boundspagination.limit- Results per page (max 50, default 20)pagination.nextToken- Cursor for next page of results
/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 latitudefilter.longitude- Center point longitudefilter.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.
Explore the Ports Database
Try these endpoints interactively in the API Explorer.