Wiki

Case Status
Log In

Wiki

 
API Call Format Description
  • RSS Feed

Last modified on 4/17/2012 12:33 PM by User.

Tags:

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.

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 info@portinfo.co.uk. Shipping Guides Ltd are recognised industry specialists in publishing port and harbour information for your various port entry requirements. For more information on our products, please visit www.portinfo.co.uk.