Case Status
Log In


Getting Started»Write your application
  • RSS Feed

Last modified on 9/2/2022 10:06 AM by User.


Write your application


The API supports the return of data in one of three datatypes, HTML, XML and JSON. The datatypes that are available for any API call are listed in the individual API calls' documentation. The client application must be able to interpret the data for further manipulation or display in these three formats.

Using the URL "<api_key>", an application can open a connection using the HTTP POST method and retrieve XML information from the web application. The structure of the XML information is defined in the documents of this wiki. In order to access the API in this manner, the client application must contain the following:

  • A means of producing valid requests to the API.
  • HTTP 1.1 compliant client implementation to send the requests to the API.
  • HTTP 1.1 compliant server implementation to receive XML information from the API.
  • An XML parser to interpret the data received from Access Manager.

The programing language for issuing and interpreting the results from these requests must be able to support the use of the XMLHttpRequest object.

Programming Languages

The XMLHTTP Object and its methods, and JSPN and JSONP are supported by the following programming languages (not an exhaustive list):

  • Javascript / AJAX (Asynchronous JavaScript And XML)
  • Javascript, using jQuery and JSON or JSONP

Browser support

The XMLHTTP Object is supported by a number of web browsers:

Internet Explorer 7 and higher, Firefox, Opera and Safari all require the use of the XMLHttpRequest object.

Internet Explorer 5.5 and 6 require the use of Microsoft's ActiveX object, "Microsoft.XMLHTTP"

Some Javascript coding is required to detect the type and version of browser, and to choose the correct XMLHttp Object.

<script type="text/javascript>
if (window.XMLHttpRequest) { // code for IE7+, Firefox, Chrome, Opera, Safari
    xmlhttp=new XMLHttpRequest();
else { // code for IE6, IE5
    xmlhttp=new ActiveXObject("Microsoft.XMLHTTP");


Requirement to use a single IP Address API key registration

The registration of the API key is linked to an IP address. Generally, this is the public IP address of your organisation's acces to the Interet. In some cases, you may have a range of IP addresses allocated. Multipe addresses are managed by using a net mask if they are all within an P address range, or multiple, single IP addresses may be registered. If an API request from a valid key is received from an IP address that hasn't been registered, the request will be rejected.

Cross-domain browsing

In addition, the use of the XMLHttpRequest to access a server which is NOT the server that delivered the original web page will cause the browser to refuse  to open the connection.

Modern web browsers will stop network connections using calls to XMLHttpRequest from making a connection to web servers other than the one which served the web page originally. If both your web pages and their XML data come from the same server, there is no problem. The web page can retrieve the data and display it as the web application intends.


However, if the data is retrieved from another server, the connection is blocked.

By using a proxy, the XMLHTTPRequest is sent to the server as if from the corporate web server, and teh data is returned from the server within the same domain as the browser. This fulfils the requirements of both the API to use the registered IP address and the browser in terms of cross-domain access.

Other solutions to the problems of cross-domain browsing include:

  • If your web server is running Apache, you can use Apache's mod_proxy or mod_rewrite to send requests from your server to another server.
  • Use JSON and dynamic <script> tags instead of XML and XMLHttpRequest. If the web services request is made from inside a dynamic <script> tag, can return a JSON object (using the .json output object and callback=function parameters in the web page code). The data returned from is treated as a JavaScript object .

Sample applications

The sample applications use the XMLHttpRequest method with jQuery libraries, AJAX and JSONP, which are described in detail here.

API General Information

The functions of the API are to search for ports using a variety of search criteria, and to list countries, regions and ports in those countries/regions. Having identified a port or ports, information about the  port can be retrieved using the main port identifier, the port_id.

Ports have a number of parts: the port record, a summary, port details, plans and photographs, ACE Reports. Photographs are treated as a type of plan, as they are images.

Plans and photographs, and ACE reports each have a list in which all plans, photographs and ACE Reports are listed, using the identifiers from which the individual objects can be retrieved. 

The general sequence for retrieving data is to identify the port_id and then to retrieve the data about the port using the port_id.

Note: Any errors that occur within are reported as HTTP 200 status codes, i.e. a normal http operation completion, as opposed to an HTTP error, such as 404, Page not found.
Every HTTP 200 response should be inspected for its associated XML to see that no error has occurred.
Error codes are listed in a separate article. Click here to read detailed information about error codes.

Identifying the port

In the examples below, all API calls are preceded by the URL,

Iterative approach

List countries:    /api/countries.xml?key=<your key here>
Iterate through the countries collection, identifying the countries

List regions: /api/country/<locode>/locales.xml?key=<your key here>
Iterate through the countries collection, identifying the country's regions

List ports in a country: /api/country/<locode>/ports.xml?key=<your key here>
Iterate through the ports collection, retrieving basic information about the ports

To list ports in a locale, retrieve the regions and use the <locale_id> to filter the list of ports returned by the call to list ports in a country.
Match <port><locale_id> with <locale><id>

Iterate through ports.xml to display a  list of ports or to identify the port with which you wish to work.


The Search API call can retrieve ports that match the search criteria.

The search criteria can include:

Country - ports in a country
Port name - ports by port name or part of a port's name (wildcard search) - not case sensitive
Locale - region of a country
Facility - find ports that have specific facilities
Positional information and range - find ports within a range of a position, in units of nm, miles or km

The search criteria can be ANDed together.

Search for ports beginning with 'a', in Denmark (DK), region of Zeeland, with fuel and drydock size 3
/api/port/search.xml?country=dk&locale=103&key=<your key here>

Search results are returned in pages of hits; the number of hits per page can be specified.
A specific page is returned by appending the &page=n parameter
The total number of results is given on each page
/api/port/search.xml?country=dk&locale=103&page=2&results=2&key=<your key here>

Iterate through search.xml to display a list of ports or to identify the port with which you wish to work.

Understanding Ports

Apart from details about the port, the port or search object has 5 important fields for the application developer:

  1. has_detail
  2. has_summary
  3. plans_count
  4. reports_count
  5. symbol_id
  6. wx_id

"has_detail", "has_summary", "plans_count" and "reports_count" are fields that indicate whether there is more information available about the port.

Pointers to more information for a port:

  Field Value Description
a. has_summary True A summary exists for this port, which can be retrieved as an html, xml or json object.
b. has_details True Detailed information exists for this port, which can be retrieved as an html, xml or json object.
c. parent_id

= piuid


!= piuid

If the parent_id equals the value of the piuid field, the port is considered a main port.

If the parent_id doesn't equal the piuid field, the port is considered a "sub_port" of the parent. It may have summary information, but won't have detailed information.

d. plans_count != 0 The port has a number of plans or photographs, a list of which can be retrieved as an xml or json object.
e. reports_count !=0 The port has a number of ACE reports, a list of which can be retrieved as an xml or json object.
f. symbol_id   The symbol_id relates directly to the filename of the port symbol provided in the images zip file.
g. wx_id   The wx_id is no longer used. To retrieve weather information for a port, use the piuid value in the call.

If has detail=0, has summary=0, and has_plans=0:
This is a port without any information, although the port itself does exist in the database. It is generally a port for which no request to publish any data has been received.

If has detail=0, has summary=0, and piuid != parent_id:
This is a subport with no information.
We display the parent in the UI with a message "Information for <child_port> contained in ...",
See Abonnema, NG

If has detail=0, has summary=1, and piuid != parent_id:
This is a subport with summary information.
We display the subport in the UI with a message "(see also <parent_port>)", and the summary information
See Aboshi, JP

If has detail=1, has summary=1, and piuid = parent_id then:
This is a real port!

Additional information about port_ids

More information about port_ids is provided here.

Getting information about a port

Retrieve the Summary Information for a port:
    See Degema, NG

Retrieve the section listing for the port
You can get this information in one call with the info.xml call
    See Degema, NG 

You can also retrieve the information section by section.
See Adelaide, AU
    Iterate through the list of sections, and gather each section in turn. 
If you know the name of a sectyion, you can gather it directly, but only the sections.xml object will tell you if it exists.

Retrieve a list of ACE Reports for a port, if reports_count > 0
    See Port Giles, AU
If ACE Reports exist then iterate through each one

Retrieve a list of Plans/Photos, if plans_count > 0
    See Calabar, NG
If Plans/Photos exist then iterate through each one
For the plan record including the link to the image
    See Calabar, NG
For the image itself, (note the standard format of the link using the port id (401) and the image id (491)) 
    See Calabar, NG

Formatting HTML Information

HTML information is formatted using "id=" and "class=" attributes to the HTML tags.

You can define your own stylesheet, using these attributes to control the layout and presentation of the HTML information.

A simple, sample stylesheet is provided in Reference Data

URLs in HTML information

Hyperlinks are used in the HTML information to provide cross-references to other section of a port, to other ports (e.g. where dry dock facilities might be available),  or to external web sites, such as those for a port authority or companies providing services.

The urls are encoded for use with, so a link to another port will be in the form <>/port/<port_id>. All URLs need to be inspected to determine whether they are valid for your implementation of the port information and whether they need to be changed to make them into a useful resourse for your users. 

Where to get more information on using the API

Additional information on using the API, and the details of the API calls, are published here:


If you would like to find out more about or our Findaport API service, please contact us at 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