Wiki

Case Status
Log In

Wiki

 
Quick Reference
  • RSS Feed

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

Tags:

Quick Reference

Click on the title of a piece of information below to go to the section giving short details on how to access that information from your application.

Notes

All requests need a valid API key. Append it to the query string. Your API key can be found on your Account's API page.

http://www.findaport.com/api/port/3279.html?key=your_api_key

Some API calls will involve the following:

  • format - The output may be available in different formats, this will be clearly stated. e.g. HTML, XML, JSON, RSS or KML
  • resource IDs - One or two resource IDs might be required, this will be clearly highlighted. e.g. port id, plan id.

Examples below are live links to the Findaport.com API. You will only need to add your API key when the call is put into the browser's address bar.

Search

By providing search criteria, such as the name of a port or a country, ports matching those criteria are returned.

URL Format: http://www.findaport.com/api/port/search.format?results=num&page=num&search_criteria
 

Parameter Value Explanation
format html, xml or json

Output format can be in HTML, XML or JSON.

JSON takes an optional parameter of 'callback' to specify the name of the callback method to wrap the output with.

results a number, e.g. 20 Search can return a large number of results and to handle this, they are returned in 'pages' of 20 results per page by default. A custom number of results per page can be set here.
page a number, e.g. 1, 2, 3, etc. Use this parameter to view 2nd, 3rd or other pages of a given search query.
search_criteria     
country=locode Find ports within a country. A country is specified using its locode.  
port=port query string Find ports with name matching the query string.  
locale=locale ID Find ports within a locale, specified by locale ID. Locale ID are retrieved using the locales.xml api call
facility[facility name]=true Find ports matching one or multiple facilities. Multiple facilities can be matched by using this criteria multiple times.  
distance_amount=number
distance_unit=[nautical miles | miles | kilometers]
latitude_degrees=number
latitude_minutes=0
latitude_hemisphere=[N | S]
longitude_degrees=number
longitude_minutes=number
longitude_hemisphere=[E | W]
Find ports within a certain distance from a location, with location specified in DMS format. Note that this search argument cannot be ANDed with the search arguments above
Examples
 
Link Explanation
http://www.findaport.com/api/port/search.html?country=dz Ports within Algeria in HTML format.
http://www.findaport.com/api/port/search.xml?results=40&page=2 Return up to 40 results of page 2 of all ports. results and page parameters can be used with any search criterias.
http://www.findaport.com/api/port/search.xml?country=dz Ports within Algeria in XML format.
http://www.findaport.com/api/port/search.json?country=dz Ports within Algeria in JSON format.
http://www.findaport.com/api/port/search.json?country=dz&callback=callbackfunc Ports within Algeria in JSON format with JSON objects wrapped in a function called 'callbackfunc'. This method of organising JSON objects is called JSONP.
http://www.findaport.com/api/port/search.xml?port=a Ports beginning with letter 'a'(not case sensitive) in XML.
http://www.findaport.com/api/port/search.xml?locale=42 Ports within locale 'Benin'(42) in XML.
http://www.findaport.com/api/port/search.xml?facility[fuel]=true Ports having 'fuel' facility in XML.
http://www.findaport.com/api/port/search.xml?facility[fuel]=true&facility[drydock3]=true Ports having 'fuel' and 'drydock3' facilities in XML.
http://www.findaport.com/api/port/search.xml?distance=1000&
distance_unit=nautical%20miles&
latitude_degrees=0&
latitude_minutes=0&
latitude_hemisphere=N&
longitude_degrees=0&
longitude_minutes=0&
longitude_hemisphere=E
Ports within 500 nautical miles of 23°0N 12°0W, in XML.

List ports in a country

List all ports in a country

URL format: http://www.findaport.com/api/country/locode/ports.format
 
Parameter Value Explanation
format xml, json or kml

Available output format

locode ISO Location Code Click here for a downloadable list of locodes
Examples
 
Link Explanation
http://www.findaport.com/api/country/dz/ports.html List Algeria's ports in HTML
http://www.findaport.com/api/country/dz/ports.xml List Algeria's ports in XML
http://www.findaport.com/api/country/dz/ports.json List Algeria's ports in JSON

Retrieve Information

Retrieve port information. The length of information can be a summary,  brief or detailed.

Port summary:
URL format: http://www.findaport.com/api/port/port_id/summary.format

Brief port information:
URL format: http://www.findaport.com/api/port/port_id.format
 
Detailed port information:
URL format: http://www.findaport.com/api/port/port_id/info.html
 
Parameter Value Explanation
format html, xml, json or rss Available output formats
port_id   The Port ID
Examples
 
Link Explanation
http://www.findaport.com/api/port/3279.html Retrieve brief port information for Abu Qir in HTML format.
http://www.findaport.com/api/port/3279.xml Retrieve brief port information for Abu Qir in XML format.
http://www.findaport.com/api/port/3279.json Retrieve brief port information for Abu Qir in JSON format.
http://www.findaport.com/api/port/3279/toc.html Retrieve Table of Contents to be used with Abu Qir's detailed output.
http://www.findaport.com/api/port/3279/toc.json Retrieve Table of Contents in JSON.
http://www.findaport.com/api/port/3279/summary.html Retrieve summary information of Abu Qir in HTML format.
http://www.findaport.com/api/port/3279/summary.json Retrieve summary information of Abu Qir in JSON format.
http://www.findaport.com/api/port/3279/info.html Retrieve detailed port information for Abu Qir in HTML format.
http://www.findaport.com/api/port/3279/info.json Retrieve detailed port information for Abu Qir in JSON format.
http://www.findaport.com/api/port/3279/info.rss Retrieve detailed port information for Abu Qir in RSS format.

ACE Report

View an individual ACE report or all ACE reports of a port.

To retrieve a list of links to ACE reports of port_id:
URL format: http://www.findaport.com/api/port/port_id/ace_reports.format

To view an individual ACE report:
URL format: http://www.findaport.com/api/ace_report/ace_id.format

 
Parameter Value Explanation
format xml or json Available output formats
ace_id   ACE report ID
port_id   Port ID
Examples
Link Explanation
http://www.findaport.com/api/port/193/ace_reports.xml Retrieve list of links to ACE reports of port with id 193 in XML format
http://www.findaport.com/api/port/193/ace_reports.json Retrieve list of links to ACE reports of port with id 193 in JSON format
http://www.findaport.com/api/ace_report/71597.xml View ACE report with ace_id of 71597 in XML format.
http://www.findaport.com/api/ace_report/71597.json View ACE report with ace_id of 71597 in JSON format.

Plans

Retrieve a list of all plans belonging to a port.

URL format: http://www.findaport.com/api/port/port_id/plans.format
 
Parameter Value Explanation
format html, xml, json or kml

Available output formats.
html output includes links to the image and to a thumbnail of the image.

port_id   Port ID
Examples
Link Explanation
http://www.findaport.com/api/port/20/plans.html List of Adelaide's plans in HTML format 
http://www.findaport.com/api/port/20/plans.xml List of Adelaide's plans in XML format
http://www.findaport.com/api/port/20/plans.json List of Adelaide's plans in JSON format
http://www.findaport.com/api/port/20/plans.kml List of Adelaide's plans in KML format

Retrieve a plan

URL Format: http://www.findaport.com/api/port/port_id/plan/plan_id.format
 
Parameter Value Explanation
format xml, json, kml, img or html

Available output formats. img will return either a GIF or JPG image depending on whether it's a port plan or photo.
xml output contains a link to the image, not the image itself.

port_id   The Port ID
plan_id   The Plan ID
Examples
Link Explanation
http://www.findaport.com/api/port/1584/plan/1860.xml View plan in XML
http://www.findaport.com/api/port/1584/plan/1860.json View plan in JSON
http://www.findaport.com/api/port/1584/plan/1860.kml View plan in KML
http://www.findaport.com/api/port/1584/plan/1860.img View a plan image. These are always in GIF image format
http://www.findaport.com/api/port/251/plan/4397.img View a port photo. These are always in JPG image format
http://www.findaport.com/api/port/251/plan/4397.html Returns HTML segment of plan image

Countries

Retrieve country information

URL Format: http://www.findaport.com/api/countries/locode.html
 
Parameter Value Explanation
locode  

Country locode
A file of locode information is available in Reference Data

Examples
Link Explanation
http://www.findaport.com/api/country/dz.html Retrieve information about Algeria

Retrieve regional information (locales)

URL Format: http://www.findaport.com/api/country/locode/locales.xml

Parameter Value Explanation
locode UN Location Code Retrieve information about regions and other administrative areas within a country

Example

Link Explanation
http://www.findaport.com/api/country/au/locales.xml Retrieve the administrative regions of Australia

 Weather

A five-day weather forecast is available for the vicinity of a Port.

URL Format: http://www.findaport.com/api/weather/port_id.format

Parameter Value Explanation
port_id   ID of Port
format xml, json or html Available formats
html format uses images from the findaport.com web site. A full set of weather images can be found herehere
Examples
Link Explanation
http://www.findaport.com/api/weather/20.xml Get five-day weather forecast in XML for Adelaide, Australia (port 20).
http://www.findaport.com/api/weather/20.json Get five-day weather forecast in JSON for Adelaide, Australia (port 20).
http://www.findaport.com/api/weather/20.html Get five-day weather forecast in HTMLfor Adelaide, Australia (port 20).

News

News and announcements are accessible to all users via RSS at:

This does not require an API key.

Version Management

All objects in Findaport.com are versioned.

Version API call

A Version API call will allow the Application to determine the current version of a port on the server:

URL Format: http://www.findaport.com/api/port/<port_id>/version.xml
 
Parameter Value Explanation
port_id   Port ID

Examples

Link Explanation

http://www.findaport.com/api/port/20/version.xml

Retrieve the current version number of the port's information on the server version

Updates API call

An Updates API call will establish what updates have been made since the version of the data quoted in the request (stored or cached by the application):

URL Format: http://www.findaport.com/api/port/<port_id>/updates.xml?version=<client_version>

Parameter Value Explanation
port_id   Port ID
client_version   Version of port or subordinate object in the client database or application

Example

Link Explanation
http://www.findaport.com/api/port/20/updates.xml?version=68000 Retrieve details of all updates to port 20 (Adelaide)since version 68000
   

Subsequent calls to the API can be used to retrieve the updated object's metadata and the object itself, e.g., for a plan, http://www.findaport.com/api/port/<port_id>/plan/<plan_id>.xml
http://www.findaport.com/api/port/<port_id>/plan/<plan_id>.gif

Error Handling

If Findaport isn't able to validate an API key, or is unable to find a requested resource, it will return an HTTP 200 error (not an HTTP 404 error, as it would if a page were not found). In the data of the returned page will be the details of the error in the format the original request expects.

  • Unrecognised API calls of any format are returned with HTTP status code 404 and a plain text error message.
  • HTML requests are returned with the error message in plain text, as we believe this is easier to parse.

XML error output:

<error>
    <code>[numerical error code]</code>
    <message>[descriptive error message</message>
  </error>
 

Table of error codes

 

 

 

 

 

Error Condition

Description

HTTP Status Code

Error Code

Error Message

Bad API call

Incorrect API call URL

404

10

Error code 10: The requested API call does not exist

API key - Not Supplied

 

200

11

No API key supplied

API key - Invalid

 

200

11

API key is invalid

API key - Expired

 

200

12

Your API key has expired

API key - Out of IP Range

 

200

13

Your IP address doesn't fall within the allowed IP range for this API key

Usage - Throttled

 

200

21

You've been throttled for unusually high usage.

Invalid Resource ID

Invalid ID for Port, Country, ACE report etc.

200

30

Various depending on requested resource type

Invalid Sub-resource Name

e.g. when requesting Port Section

200

31

 

 

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.