Introduction
This section presents the documentation for the API calls available in the Findaport API (https://www.findaport.com/api)1. Each call is documented to describe the input parameters required for each of the API calls’ formats, the call's format itself, and gives examples showing the input and output for each of the calls.
Call Format
The summary below shows the format required to construct a valid API call.
Each call is appended to the Findaport API endpoint as a path in which the input parameters of the call and the output format are specified.
Every call has a minimum of one required querystring parameter, the API Key. Any additional parameters required by the call are specified in the same querystring.
The call format is:
<API Endpoint>{/<object>}{/<qualifier>}{/<section>}/<output>.<format>?<querystring>
where:
< and > represent the delimiters for the parameters required by the API call. The delimiters are purely visual identifiers and are not entered in the API call itself.
{ and } represent delimiters showing optionality; input parameters may be present depending on the actual API call. The delimiters are purely visual identifiers and are not entered in the API call itself.
API Endpoint is always www.findaport.co.uk/api. The one exception to this is the RSS API call (see xxx).
Object may be one of Port, ACE_Report, Plan, Country, Misc, Countries. Other objects include Submit, Weather, xxx.
Qualifier may be an ID, such as a port_id or locode.
Section may be a part of a port’s details, such as Plan or Section. In the case of Section, the section name is given in the <Output> parameter.
Output is the name of the list of information, such as ACE_report, countries, locales, locodes, plans, ports, or toc.
Where specific output information is required rather than a list, output is the ID of the desired object, such as an ACE_id, port_id or plan_id.
Where a section of port information is required, the output is the name of the section, such as fuel, intro, etc.
“Search” in this position identifies the fact that the output will be a set of search results, where the search criteria have been supplied in the querystring.
Format describes the format of the output document. Depending on the API call, a variety of different output formats are available, including:
- JSON
- XML
- KML
- HTML
The applicability of any of the formats to an API call is described in "Output Formats" below.
Querystring Parameters
The querystring consists of one required querystring parameter and one, none or many optional querystring parameters:
?key=APIKey{&<param_1>{&<param_2>…{&<param_n>}}...}
Required querystring parameter:
key=APIKey where APIKey is the API Key issued by Shipping Guides Limited
Optional querystring parameters:
&<param_n> optional parameters required by the API call
Example
If your API key is abcdefg12345, and you would like to display the port summary for Algiers (port_ID=65) in HTML format, the full API call will be:
www.findaport.com/api/port/65/summary.html?key=abcdefg12345
Output Formats
The table below summarises the output formats available from various API calls.
API Call | JSON | XML | KML | HTML | Notes |
---|---|---|---|---|---|
Port | |||||
search | Yes | Yes | Yes | to search for a set of ports based on specific criteria | |
view | Yes | Yes | Yes | ||
summary | Yes | to view the summary information for a port | |||
toc | Yes | to view a table of contents for a port | |||
info | Yes | Yes | Yes | ||
sections list | Yes | Yes | Outputs a list of port's sections. | ||
section | Yes | Yes | Outputs a port's section. | ||
version | Yes | Yes | Outputs the highest version number of the port or parts | ||
updates | Yes | Yes | Outputs a list of updates since a version number supplied by the calling application | ||
ACE Report | |||||
list | Yes | Yes | List ACE reports for a port | ||
view | Yes | Yes | Yes | View an ACE report | |
Plan | |||||
list | Yes | Yes | Yes | view list of plans belonging to port | |
view | Yes | Yes | Yes | Also available in GIF for port plans and JPG for port photos | |
Country | |||||
view | Yes | to view the detailed information about a country | |||
locales | Yes | Yes | to list regions/provinces/states, etc of a country | ||
ports | Yes | Yes | Yes | view ports belonging to country | |
Misc | |||||
weather | Yes | Yes | to view the weather information for a port | ||
News | |||||
News | RSS Output | ||||
Search | |||||
Port Search | GeoRSS output | ||||
Locale | |||||
list | to list regions/provinces/states, etc of all countries |
If you would like to find out more about Findaport.com or our Findaport API service, please contact us at findaport@oneocean.com. Shipping Guides Ltd are recognised industry specialists in publishing environmental, compliance and navigational software and port information for your various requirements. For more information on our products, please visit www.oneocean.com.
Footnotes
1 Findaport only uses https protocol now. Any references in the documentation to http should be read to mean https