Title Index
Recently Changed
Page Hierarchy
Incomplete
Tags
The operation of the API is based around each port having a different Port ID value (fieldname piuid). Working out which piuid value to use to access various parts of the API can sometimes be tricky.
The main operation is the Port View call. It comes in 3 flavours:
- Port Record - returns the metadata for a port
- Port Summary - returns the summary port information for the port
- Port Detail - returns the full detailed port entry for a port
The Port Record should be your first port of call. It takes the format
http://findaport.com/api/port/<id>.<format>?key=<your_api_key>
where <id> is the id of the port requested, and <format> defines the data format returned which can be one of xml, json, html or rss. For the purposes of this discussion we will focus exclusively on the xml data format, but the other formats return similarly structured data.
With the Port Record record call, the id used should always be the piuid field either in a supplied data extract or in the returned data from a search query. So assuming we want the record for Aabenraa in Denmark the call would be
http://findaport.com/api/port/1.xml?key=<your_api_key>
This should return something like this
<port> <piuid>1</piuid> <port>Aabenraa</port> <locode>DK</locode> <type>Port</type> <port_lvl>4</port_lvl> <locale_id>99</locale_id> <unctad_port_code>AAB</unctad_port_code> <symbol_id>807</symbol_id> <lat>55.039722</lat> <lng>9.4243</lng> <parent_id>1</parent_id> <seo_url>http://www.findaport.com/port-of-aabenraa</seo_url> <web>http://www.aabenraaport.dk</web> <has_detail>1</has_detail> <has_summary>1</has_summary> <plans_count>3</plans_count> <reports_count>0</reports_count> <wx_id>4004</wx_id> <wx_name>Abenra</wx_name> <verified_date>2015-08-20</verified_date> <version>371775</version> <header> <div id="hdr"> <div class="hd5"> <span class="b">Aabenraa</span> .... </div> <div class="p">Also see <span>Ensted and General before first Denmark port</span></div> </div> </header> </port>
For our purposes today, it's the elements highlighted in yellow that we are interested in.
There are 4 normal combinations of data in those elements, and they are described in the table below:
| Condition | has_detail | has_summary | Description | Summary In | Detail In | |
|---|---|---|---|---|---|---|
| 1. | piuid = parent_id | 1 | 1 | Standard Port | piuid | piuid |
| 2. | piuid = parent_id and port_lvl = 6 | 1 | 0 | Small number of records with no max size - closed ports, new ports awaiting details, etc | n/a | piuid |
| 3. | piuid <> parent_id | 0 | 1 | Subport with own max size information - data contained in parent_id port | piuid | parent_id |
| 4. | piuid <> parent_id | 0 | 0 | Subport or alternate name - data contained in parent_id port | n/a | parent_id |
Any other data combination is an error condition and should be reported to Shipping Guides.
Condition 1:
This is a standard port entry, e.g. Aabenraa (piuid=1) or Rotterdam (piuid=2421)
has_detail = 1 and
has_summary = 1 and
piuid = parent_id
Typical API URLs:
- Port Record - http://findaport.com/api/port/1.xml?key=<your_api_key>
- Summary - http://findaport.com/api/port/1/summary.xml?key=<your_api_key>
- Detail - http://findaport.com/api/port/1/info.xml?key=<your_api_key>
Condition 2:
There are a small number of otherwise standard port entries, e.g. Lucina Marine Terminal (piuid=1606), which reference ports that are either in the process of opening or closing, where we do not have maximum size or other summary information and so therefore do not have a summary record. This is indicated by has_summary = 0 in the port record. The API example URLs below may well be out of date but were current when this wiki was first written (please advise support@findaport.com if they return unexpected results and we will endeavour to update them)
has_detail = 1 and
has_summary = 0 and
piuid = parent_id
Typical API URLs:
- Port Record - http://findaport.com/api/port/1606.xml?key=<your_api_key>
- Summary - http://findaport.com/api/port/1606/summary.xml?key=<your_api_key> returns an error
- Detail - http://findaport.com/api/port/1606/info.xml?key=<your_api_key> - returns a shortened or even empty document, perhaps saying "Terminal closed" or similar
Condition 3:
This is a standard SubPort entry. Many ports and terminals have subports. So the system allows searching and referencing of standard entries using these subport names and id's. This condition refers to those subports that have a summary record, usually those where we have details of the maximum size vessel which the subport is capable of handling. An example might be Europoort as a subport of Rotterdam (Europoort piuid=721 and parent_id=2421, and Rotterdam piuid=2421). For the detail record, the API must be passed the parent_id value, and the data returned will be the entire entry for Rotterdam
has_detail = 0 and
has_summary = 1 and
piuid != parent_id
Typical API URLs:
- Port Record - http://findaport.com/api/port/721.xml?key=<your_api_key>
- Summary - http://findaport.com/api/port/721/summary.xml?key=<your_api_key> The summary record returned is specific to Europoort
- Detail - http://findaport.com/api/port/2421/info.xml?key=<your_api_key> The port detail is the entry for Rotterdam
Condition 4:
This is a standard Alias entry. Many ports and terminals have aliases, alternate names and subports names which are in common usage. So the system allows searching and referencing of standard entries using these alias names and id's. An example might be Rijnpoort as a subport of Rotterdam (Rijnpoort piuid=721 and parent_id=2421, and Rotterdam piuid=2421). This condition refers to those aliases for which there is no summary record. Similarly to Condition 3, the parent_id is used the detail call.
has_detail = 0 and
has_summary = 0 and
piuid != parent_id
Typical API URLs:
- Port Record - http://findaport.com/api/port/721.xml?key=<your_api_key>
- Summary - http://findaport.com/api/port/721/summary.xml?key=<your_api_key> returns an error
- Detail - http://findaport.com/api/port/2421/info.xml?key=<your_api_key> The port detail is the entry for Rotterdam
Conclusion
When making a summary API call, the value in the has_summary field in the port record needs to be checked first to ensure it has a value of 1. Otherwise an error will be returned.
Additionally, when producing a list of ports to a user, perhaps in a dropdown, with the intention of displaying a summary record, it would be wise to exclude all those records with has_summary =0.
To return a port detail record, the parent_id value should be used in the API call to reference the port. Additionally, if has_detail = 0, it might be sensible to display a message to the user to warn that the data returned will be from a different port to that being requested originally. In findaport.com, we show this message in these circumstances:
