![GEOMAR Logo](/images/geomar_logo.png) This server hosts services for positions of ships as well as tracks and maps of expeditions. The services are implemented in a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)-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](https://en.wikipedia.org/wiki/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 [{{% base_url %}}]({{% base_url %}}) # Table of Contents # [TOC] 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](http://www.geomar.de/forschen/expeditionen/) >`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](http://www.geomar.de/forschen/expeditionen/) 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](http://www.geomar.de/forschen/expeditionen/) might contain more expeditions, since expeditions remain on the expedition page a little while after their planned end date. {{% maps_common_params %}} ### Example Usage ### Below is a complete example of an html-page embedding the map with current positions. ```html


Aktuelle Position/Arbeitsgebiet deutscher Forschungsschiffe unter GEOMAR Fahrtleitung

``` The resulting page will look like this: {{% map_current_positions_demo %}}

## /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. {{% maps_common_params %}} ### Example Usage ### Below is an example of an html string embedding the map with current position of RV Alkor. ```html
``` The resulting map is found at {{% service_link endpoint=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) {{% maps_common_params %}} ### Example Usage ### Below is an example of an html string embedding the map with current position of RV Alkor. ```html
``` http://localhost:8080/maps/legMap?lang=de&render=true&leg=AL499 The resulting map is found at {{% service_link endpoint=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 {{% service_link endpoint=expeditions/ %}} without any parameter will list all known expedition labels: ```json [ "AL0712", "AL1012", "AL1212", [...] "SO267", "SO268/1", "SO268/2", ] ``` The same list is als returned by {{% service_link endpoint=expeditions/list %}} , {{% service_link endpoint=tracks/ %}} or {{% service_link endpoint=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*: - {{% service_link endpoint=expeditions/AL/list %}} - {{% service_link endpoint=expeditions/M/list %}} - {{% service_link endpoint=expeditions/MSM/list %}} - {{% service_link endpoint=expeditions/POS/list %}} - {{% service_link endpoint=expeditions/SO/list %}} ## /expeditions/*leg_label*/webinfo ## Returns information about the expedition (Chief Scientist, summary, related reports, ...) in a JSON format ### Example Usage ### {{% service_link endpoint=expeditions/SO255/webinfo %}} ```json { "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 ### {{% service_link endpoint=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](http://geojson.org/) format. ### Example Usage ### {{% service_link endpoint=expeditions/SO255/researchArea %}} ```json { "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](http://geojson.org/) format. ### Example Usage ### {{% service_link endpoint=expeditions/SO255/positionResearchArea %}} ```json { "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](http://geojson.org/) format. Besides coordinates, the returned JSON is enriched with supplementary information about the port. ### Example Usage ### {{% service_link endpoint=expeditions/SO255/portDeparture %}} ```json { "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](http://geojson.org/) format in any case. ### Example Usage ### {{% service_link endpoint=expeditions/SO255/bestPosition %}} ## /expeditions/*leg_label*/track ## Returns the track for the expedition, enconded in the [GeoJSON](http://geojson.org/) 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](https://portal.geomar.de/osis) is returned. Besides coordinates and time stamps, the returned JSON is enriched with supplementary information about the expedition. ### Example Usage ### {{% service_link endpoint=expeditions/SO255/track %}} ```json { "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" } ```