Wiki

Case Status
Log In

Wiki

 
Ports and subports - which id …
  • RSS Feed

Last modified on 11/20/2015 1:55 PM by User.

Ports and subports - which id fields to use

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:

  1. Port Record - returns the metadata for a port
  2. Port Summary - returns the summary port information for the port
  3. 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:

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:

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:

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:

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: