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.

Some API calls will involve the following:

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

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

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.

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

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

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:

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:

Table of error codes

 

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.