API Call Format Description

Introduction

This section presents the documentation for the API calls available in the Findaport API (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.