Title Index
Recently Changed
Page Hierarchy
Incomplete
Tags
Requirements
The findaport.com 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 "https://www.findaport.com/...?key=<api_key>", an application can open a connection using the HTTP POST method and retrieve XML information from the findaport.com web application. The structure of the XML information is defined in the documents of this wiki. In order to access the findaport.com 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 findaport.com API.
- HTTP 1.1 compliant server implementation to receive XML information from the findaport.com 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
- ASP.NET
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");
}
...
</script>
Requirement to use a single IP Address
findaport.com 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 findaport.com 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 findaport.com 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_proxyormod_rewriteto 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, findaport.com can return a JSON object (using the.jsonoutput object andcallback=function parameters in the web page code). The data returned from findaport.com 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 Findaport.com 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, https://www.findaport.com.
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.
Search
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:
- has_detail
- has_summary
- plans_count
- reports_count
- symbol_id
- 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 findaport.com UI with a message "Information for <child_port> contained in ...",
See Abonnema, NG https://www.findaport.com/api/port/12.xml?key=
If has detail=0, has summary=1, and piuid != parent_id:
This is a subport with summary information.
We display the subport in the findaport.com UI with a message "(see also <parent_port>)", and the summary information
See Aboshi, JP https://www.findaport.com/api/port/13.xml?key=
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 https://www.findaport.com/api/port/598/summary.xml?key=
Retrieve the section listing for the port
You can get this information in one call with the info.xml call
See Degema, NG https://www.findaport.com/api/port/598/info.xml?key=
You can also retrieve the information section by section.
See Adelaide, AU https://www.findaport.com/api/port/20/sections.xml?key=
Iterate through the list of sections, and gather each section in turn.
https://www.findaport.com/api/port/20/section/intro.xml?key=
https://www.findaport.com/api/port/20/section/location.xml?key=
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 https://www.findaport.com/api/port/2161/ace_reports.xml?key=
If ACE Reports exist then iterate through each one
https://www.findaport.com/api/ace_report/171706.xml?key=
Retrieve a list of Plans/Photos, if plans_count > 0
See Calabar, NG https://www.findaport.com/api/port/401/plans.xml?key=
If Plans/Photos exist then iterate through each one
For the plan record including the link to the image
See Calabar, NG https://www.findaport.com/api/port/401/plan/491.xml?key=
For the image itself, (note the standard format of the link using the port id (401) and the image id (491))
See Calabar, NG https://www.findaport.com/port/401/plan/491.gif
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 Findaport.com, so a link to another port will be in the form <findaport.com>/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:
- Quick Reference - A quick reference to some of the more common API calls
- Reference Data - downloadable resources
- List of API Calls - a list of all the API calls, their formats and returned data
- Error Codes - a list of the errors that could be returned and must be handled