GEOMAR Services for Positions, Tracks and Maps

GEOMAR Logo

This server hosts services for positions of ships as well as tracks and maps of expeditions. The services are implemented in a REST-like fashion, meaning that each function is accessible by a unique URL using a web browser or script. Parameters can be passed to influence what is returned by the Function. The services respond by either returning data in the human-readable JSON format or by providing html+javascript which can be embedded in a web site.

The unique URLs of the service functions are generated using a service base-url together with so-called endpoints. Below, each service endpoint is described in detail ans usage examples are given.

The map-generation dataservice is the main service providing posotions, tracks and maps. It's base-url is https://maps.geomar.de/mapgen_ds/

The map-generation dataservice provides endpoints for maps, expedition info, ship tracks and ship positions. These provided endpoints are described below.

/maps

The endpoints under /maps serve html+js snippets for embedding complete maps into websites. This endpoint is probably the most usefull one as it provides maps as a complete product, while all other endpoints provide the information used in these maps.

Currently, only one endpoint is available (currentPositions, see below). Planned but not yet implemented maps include:

single expeditions: detailed map of a single leg/ expedition, including
- Ports of arrival and departure
- research area
- track
multi-track maps: maps for tracks from multiple legs/ expeditions
- expedition labels are passed as parameters (e.g. SO255, SO256, SO258), tracks for these expeditions are then drawn together on the map

/maps/currentPositions

The /maps/curentPositions endpoint returns a map with the current positions of all active GEOMAR ships.
A maker for each ship bearing the ship's short token is positioned on the map. When these markers are selected, a popup with additional information about the expedition opens.

The position displayed depends on data availability. Where available, underway data send home by the ships is used. Positions using underway data have a little time stamp on the bottom right corner of the marker popup indicating when exactly the ship was at the shown position.
If underway data is not available, the position of the expeditions research area is shown. The marker is placed in the geographical center of the research area and the popup-info shows 'research area' un the bottom.
For some expeditions, research areas are not defined. In this case, the port of departure is shown and the popup is annotated accordingly.

Parameters

view: official|extended|all, default official

offical will show only the expeditions shown on the geomar expedition page
extended Alkor and Poseidon cruises are shown even if they do not belong to an expedition, e.g. if ships are on a transit passage. If available, expedition info for the ship's current expeditions will be shown even if web_info is set to not visible.
all all vessels with a known position are shown, regardless of the content of the geomar expedition page

Please note that only expeditions that are currently active are shown (i.e. now is between expedition start date and expedition end date). The expeditions currently listet on the geomar expedition page might contain more expeditions, since expeditions remain on the expedition page a little while after their planned end date.

lang: en|de, default en
Language setting for popup info. Setting remains valid for all subsequent calls to maps/ endpoints untill selection changes.

render: true|false, default false If set to true, the endpoint output is wrapped inside a html-template, making it possible to render the endpoint output on its own, not needing to embed it. This is pretty much for testing purposes only.

lat: number, default 20.0 Latitude of map center point

lon: number, default 30.0 Longitude of map center point

zoom: number|true, default 2 Zoom lavel of the map. If trueis passed, the map is zoomed to an extend where it is showing all features on the map. In this case, lat and lon parameters are ignored.

Example Usage

Below is a complete example of an html-page embedding the map with current positions.

<!DOCTYPE html>
<html>
    <head>
        <!-- load js-libraries and css.  -->
        <!-- jquery is needed, feel free to insert your preffered version here -->
        <script src="https://maps.geomar.de/mapgen_ds/assets/jquery-2.2.0.min.js"></script>
        <!-- geomap.js contains leaftet and other third party libraries among GEOMAR specific code -->
        <script src="https://maps.geomar.de/mapgen_ds/assets/geomap.js" type="text/javascript"></script>
        <link rel="stylesheet" href="https://maps.geomar.de/mapgen_ds/assets/geomap.css" />            
    </head>
    <body>
       <h1 class="csc-firstHeader">Expeditionen</h1>
        <p>Aktuelle Position/Arbeitsgebiet deutscher Forschungsschiffe unter GEOMAR Fahrtleitung</p>
        <!-- the element containing the map will be named geomar_expedition_map, use css to set size etc -->
        <style>
          #geomar_expedition_map {
             width: 730px;
             height: 500px;
             margin: auto;
           }
        </style>
        <!-- the snippet below embeds the map -->
        <div id="geomap"></div>
        <!-- script loads generated html/js from maps.geomar.de into <div>-element above -->
        <script type="text/javascript"> 
        $("#geomap").load("https://maps.geomar.de/mapgen_ds/maps/currentPositions?lang=en&view=official")
        </script>
    </body>
</html>

The resulting page will look like this:

Expeditionen

Aktuelle Position deutscher Forschungsschiffe unter GEOMAR Fahrtleitung

/maps/currentPosition

This map shows the current position of one ship. If the ship is currently on a cruise, related features such as track, research area and ports of departure and return are also displayed. i.e. the legMap (see below) of the current cruise is shown.

Parameters

platform or ship: the ship for which the map is generated.

Example Usage

Below is an example of an html string embedding the map with current position of RV Alkor.

<div id="geomap"></div>
<script type="text/javascript"> 
    $("#geomap").load("https://maps.geomar.de/mapgen_ds/maps/currentPosition?lang=de&platform=alkor")
</script>

The resulting map is found at https://maps.geomar.de/mapgen_ds/maps/currentPosition?lang=en&platform=alkor&render=true

/maps/legMap

This endpoint serves a map with features for a single expedition, including track, ports of departure and return and resaerch areas.

Parameters

label or leg or leg_label Leg label/ expedition token as used in OSIS. Examples: POS517, SO255, AL499. In case of split cruises, e.g. POS518/1, POS518/2, replace the slash / with a dash -: POS518-1, POS518-2.

osisId or webInfId or expeditionId The ID of the OSIS WebInfExpedition-entry for the cruise of interest. For example the id for POS518/2 is 342569. Used for compability reason with OSIS and otehr tools. If this is given, the label parameter is ignored in favour of this parameter.

showtrack: true|false, default true If true, show leg track (if data is available)

showports: true|false, default true If true, show ports departure and return

showresearcharea: true|false, default true If true, show research area of expedition (if data is available)

Example Usage

Below is an example of an html string embedding the map with current position of RV Alkor.

<div id="geomap"></div>
<script type="text/javascript"> 
    $("#geomap").load("https://maps.geomar.de/mapgen_ds/maps/legMap?lang=en&leg=AL499")
</script>

http://localhost:8080/maps/legMap?lang=de&render=true&leg=AL499 The resulting map is found at https://maps.geomar.de/mapgen_ds/maps/legMap?lang=en&render=true&leg=AL499 and looks like this:

/expeditions

The expeditions Endpoint serves information about specific expeditions, identified by heir label, e.g. SO255, M138 etc.

Calling https://maps.geomar.de/mapgen_ds/expeditions/ without any parameter will list all known expedition labels:

[
    "AL0712",
    "AL1012",
    "AL1212",
    [...]
    "SO267",
    "SO268/1",
    "SO268/2",
]

The same list is als returned by https://maps.geomar.de/mapgen_ds/expeditions/list , https://maps.geomar.de/mapgen_ds/tracks/ or https://maps.geomar.de/mapgen_ds/tracks/list/

/expeditions/platform_token/list

(also reached by /expeditions/list?platform=platform_token and tracks/list?platform=platform_token)
Lists known expedition labels for a specific platform. Recognized platform tokens are AL,M, MSM, POS and SO:

/expeditions/leg_label/webinfo

Returns information about the expedition (Chief Scientist, summary, related reports, ...) in a JSON format

Example Usage

https://maps.geomar.de/mapgen_ds/expeditions/SO255/webinfo

{
    "expedition": {
        "arrival": "1491868800",
        "attendance": null,
        "chief_scientist": "Kaj Hoernle",
        "departure": "1488412800",
        "expedition_type": "sea",
        "expeditiondetails": 
        [...]
    }
}

/expeditions/leg_label/popupinfo

Generates html code used in the info popup of the maps. Uses information from the webinfo.

Parameters

lang: en|de, default en
Language setting for popup info.

Example Usage

https://maps.geomar.de/mapgen_ds/expeditions/SO255/popupinfo?lang=en

/expeditions/leg_label/researchArea

Returns information about the extend and position of the expedition's research area. The research area is returned as a georeference polygon (usually a rectangle), enconded in the GeoJSON format.

Example Usage

https://maps.geomar.de/mapgen_ds/expeditions/SO255/researchArea

{
    "geometry": {
        "coordinates": [
            [177.5,-28],
            [184.5,-28],
            [184.5,-36],
            [177.5,-36],
            [177.5,-28]
        ],
        "type": "Polygon"
    },
    "id": "SO255_research_area",
    "properties": {
        "leg_label": "SO255",
        "platform": "Sonne"
    },
    "type": "Feature"
}

/expeditions/leg_label/positionResearchArea

Returns a the geographic center of the expedition's research area, enconded in the GeoJSON format.

Example Usage

https://maps.geomar.de/mapgen_ds/expeditions/SO255/positionResearchArea

{
    "geometry": {
        "coordinates": [181.0,-32.0],
        "type": "Point"
    },
    "id": "SO255_research_area",
    "properties": {
        "leg_label": "SO255",
        "platform": "Sonne"
    },
    "type": "Feature"
}

/expeditions/leg_label/portDeparture

Returns a the geographic position of the expedition's port of departure, enconded in the GeoJSON format. Besides coordinates, the returned JSON is enriched with supplementary information about the port.

Example Usage

https://maps.geomar.de/mapgen_ds/expeditions/SO255/portDeparture

{

    "geometry": {
        "coordinates": [174.77,-36.85],
        "type": "Point"
    },
    "id": "port_departure_SO255",
    "properties": {
        "leg_id": 341032,
        "leg_label": "SO255",
        "platform": "Sonne",
        "port_bodc_entrykey": "BSH1210",
        "port_call_date": "2017-03-02",
        "port_call_type": "Departure",
        "port_class": "de.kdmi.metadata.Port",
        "port_country": "New Zealand",
        "port_lat": -36.85,
        "port_lon": 174.77,
        "port_name": "Auckland",
        "visible": true,
        "webinf_id": 341934
    },
    "type": "Feature"

}

/expeditions/leg_label/bestPosition

Returns the most suited position for an expedition. Which position is most suitable depends on a number of factors: - if the realtime data is available and the expedition is currently underway, the most current known position of the research vessel is returned - if no realtime data is available, or if the expedition is finished or not yet underway, the position of the research area is returned - if the case above is true, but no research area was defined for an expedition, the port of departure is returend instead

The information is returend enconded in the GeoJSON format in any case.

Example Usage

https://maps.geomar.de/mapgen_ds/expeditions/SO255/bestPosition

/expeditions/leg_label/track

Returns the track for the expedition, enconded in the GeoJSON format. If the expedition is currently underway, realtime data is used to generate the track where available. Dor completed expeditions, the lag track as available from OSIS is returned. Besides coordinates and time stamps, the returned JSON is enriched with supplementary information about the expedition.

Example Usage

https://maps.geomar.de/mapgen_ds/expeditions/SO255/track

{

    "features": [
        {
            "geometry": {
                "coordinates": [
                    [175.52833, -36.38333, 0.0],
                    [...],
                    [174.78233, -36.84388,0.0]
                ],
                "type": "LineString"
            },
            "id": "341032",
            "properties": {
                "description": [...],
                "name": "SO255-track",
                "styleUrl": "#timelineTrack",
                "times": [
                    "2017-03-03T05:35:25Z",
                    [...],
                    "2017-04-10T19:55:25Z"
                ]
            },
            "type": "Feature"
        }
    ],
    "properties": {
        "leg_label": "SO255",
        "name": "SO255",
        "platform": "Sonne"
    },
    "type": "FeatureCollection"
}

Table of Contents

/maps

/maps/currentPositions

Parameters

Example Usage

Expeditionen

/maps/currentPosition

Parameters

Example Usage

/maps/legMap

Parameters

Example Usage

/expeditions

/expeditions/platform_token/list

/expeditions/leg_label/webinfo

Example Usage

/expeditions/leg_label/popupinfo

Parameters

Example Usage

/expeditions/leg_label/researchArea

Example Usage

/expeditions/leg_label/positionResearchArea

Example Usage

/expeditions/leg_label/portDeparture

Example Usage

/expeditions/leg_label/bestPosition

Example Usage

/expeditions/leg_label/track

Example Usage