Integration

Ports DB comes in two flavors which are available after registration.

Free account

Free option allows clients to access basic information about ports. Free account is immediately activated after finishing sing up process.

Professional account

This type of account provides full access to the ports database. Professional subscription is chargeable and valid within a year starting from the date of payment confirmation.

Security

Ports DB uses simple token authentication. The token can be found in profile's Settings menu under API Token section.

Please note, PortsDB can be accessed via https://portsdb-jsrv.rhcloud.com and http://www.portsdb.com (alias). While both are valid and can be used interchangeably for integration purposes we strongly recommend to use the former host via SSL connectivity.

Important

You should NEVER transmit tokens over a non-HTTPS connection

For clients to authenticate, the token key should be included in the Authorization HTTP header. The key should be prefixed by the string literal "Token", with whitespace separating the two strings.

For example:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

API overview

To make the PortsDB API explorable we provide convenient browsable documentation. Registration is required in order to get full access to the services.

PortsDB API documentation

Filtering

PortsDB provides multiple ways for searching, filtering and ordering data.

Search is enabled by using "search" keyword in query string. For example:

https://portsdb-jsrv.rhcloud.com/api/ports?search=rotterdam

Searches will use case-insensitive partial matches. The search parameter may contain multiple search terms (for items that enable searching by multiple fields, e.g. searching ports by port name and/or alternative name), which should be whitespace and/or comma separated. If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched.

If you need simple equality-based filtering, you can specify the set of fields you wish to filter against. This will allow you to make requests such as:

https://portsdb-jsrv.rhcloud.com/api/ports?country=Italy&max_dwt_gte=385000

Keyword "ordering" allows user to sort results. For example, to order ports by portname:

https://portsdb-jsrv.rhcloud.com/api/ports?ordering=portname

The client may also specify reverse orderings by prefixing the field name with '-', like so:

https://portsdb-jsrv.rhcloud.com/api/ports?ordering=-portname

Multiple orderings may also be specified:

https://portsdb-jsrv.rhcloud.com/api/ports?ordering=status,max_dwt

Lookup fields

Entity Filtering fields Search fields Ordering fields
Port 'portname', 'status', 'unlocode', 'country', 'max_dwt', 'max_dwt_gte' *, 'max_dwt_lte' ** 'portname', 'full_port_name', 'alternative_name' 'portname', 'status', 'max_dwt'
Terminal 'terminal_name', 'facility_type', 'port_name', 'port_id', 'latitude_degrees', 'latitude_minutes', 'latitude_indicator', 'longitude_degrees', 'longitude_minutes', 'longitude_indicator', 'dec_latitude', 'dec_longitude', 'latitude_degrees_gte', 'latitude_minutes_gte', 'latitude_indicator_gte', 'longitude_degrees_gte', 'longitude_minutes_gte', 'longitude_indicator_gte', 'dec_latitude_gte', 'dec_longitude_gte', 'latitude_degrees_lte', 'latitude_minutes_lte', 'latitude_indicator_lte', 'longitude_degrees_lte', 'longitude_minutes_lte', 'longitude_indicator_lte', 'dec_latitude_lte', 'dec_longitude_lte' 'terminal_name', 'port_name' 'terminal_name', 'facility_type'
Berth 'berth_name', 'berth_status', 'facility_type', 'port_name', 'port_id', 'latitude_degrees', 'latitude_minutes', 'latitude_indicator', 'longitude_degrees', 'longitude_minutes', 'longitude_indicator', 'dec_latitude', 'dec_longitude', 'latitude_degrees_gte', 'latitude_minutes_gte', 'latitude_indicator_gte', 'longitude_degrees_gte', 'longitude_minutes_gte', 'longitude_indicator_gte', 'dec_latitude_gte', 'dec_longitude_gte', 'latitude_degrees_lte', 'latitude_minutes_lte', 'latitude_indicator_lte', 'longitude_degrees_lte', 'longitude_minutes_lte', 'longitude_indicator_lte', 'dec_latitude_lte', 'dec_longitude_lte' 'berth_name', 'port_name' 'berth_name', 'berth_status', 'facility_type'
Country 'country_name', 'area' 'country_name' 'country_name', 'area'

*gte suffix denotes greater or equal lookup type

**lte suffix denotes less or equal lookup type

Additional filters

If you need additional filters to be added please make an appropriate request to our support team at protsdb@gmail.com or leave comments on the discussion thread at the bottom of this page.