API Call Format Description

Introduction

This section presents the documentation for the API calls available in the Findaport API (https://www.findaport.com/api)¹. 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

 

Footnotes

¹ Findaport only uses https protocol now. Any references in the documentation to http should be read to mean https