How to find geometry/shape of a Here Maps Link Id

Question

I have a list of Here Maps link Ids. I want to get their geometries. I tried calling v7 calculateroute REST API, passing a single link_id in waypoint0 and waypoint1 as below,

https://route.ls.hereapi.com/routing/7.2/calculateroute.json?apiKey={API_KEY}&mode=fastest;car&waypoint0=link!-893783351&waypoint1=link!-893783351&routeAttributes=notes&linkAttributes=shape,speedLimit

{
    "response": {
        "metaInfo": {
            "timestamp": "2021-09-28T04:03:39Z",
            "mapVersion": "8.30.124.155",
            "moduleVersion": "7.2.202138-9419",
            "interfaceVersion": "2.6.77",
            "availableMapVersion": [
                "8.30.124.155"
            ]
        },
        "route": [
            {
                "waypoint": [
                    {
                        "linkId": "+893783351",
                        "mappedPosition": {
                            "latitude": 26.711034,
                            "longitude": -80.1374786
                        },
                        "originalPosition": {
                            "latitude": 26.711034,
                            "longitude": -80.1374786
                        },
                        "type": "stopOver",
                        "spot": 0.4929245,
                        "sideOfStreet": "neither",
                        "mappedRoadName": "",
                        "label": "",
                        "shapeIndex": 0,
                        "source": "user"
                    },
                    {
                        "linkId": "+893783351",
                        "mappedPosition": {
                            "latitude": 26.711034,
                            "longitude": -80.1374786
                        },
                        "originalPosition": {
                            "latitude": 26.711034,
                            "longitude": -80.1374786
                        },
                        "type": "stopOver",
                        "spot": 0.4929245,
                        "sideOfStreet": "neither",
                        "mappedRoadName": "",
                        "label": "",
                        "shapeIndex": 1,
                        "source": "user"
                    }
                ],
                "mode": {
                    "type": "fastest",
                    "transportModes": [
                        "car"
                    ],
                    "trafficMode": "disabled",
                    "feature": []
                },
                "shape": [
                    "26.711034,-80.1374786",
                    "26.711034,-80.1374786"
                ],
                "leg": [
                    {
                        "start": {
                            "linkId": "+893783351",
                            "mappedPosition": {
                                "latitude": 26.711034,
                                "longitude": -80.1374786
                            },
                            "originalPosition": {
                                "latitude": 26.711034,
                                "longitude": -80.1374786
                            },
                            "type": "stopOver",
                            "spot": 0.4929245,
                            "sideOfStreet": "neither",
                            "mappedRoadName": "",
                            "label": "",
                            "shapeIndex": 0,
                            "source": "user"
                        },
                        "end": {
                            "linkId": "+893783351",
                            "mappedPosition": {
                                "latitude": 26.711034,
                                "longitude": -80.1374786
                            },
                            "originalPosition": {
                                "latitude": 26.711034,
                                "longitude": -80.1374786
                            },
                            "type": "stopOver",
                            "spot": 0.4929245,
                            "sideOfStreet": "neither",
                            "mappedRoadName": "",
                            "label": "",
                            "shapeIndex": 1,
                            "source": "user"
                        },
                        "length": 0,
                        "travelTime": 0,
                        "maneuver": [
                            {
                                "position": {
                                    "latitude": 26.711034,
                                    "longitude": -80.1374786
                                },
                                "instruction": "Take ramp.",
                                "travelTime": 0,
                                "length": 0,
                                "id": "M1",
                                "_type": "PrivateTransportManeuverType"
                            },
                            {
                                "position": {
                                    "latitude": 26.711034,
                                    "longitude": -80.1374786
                                },
                                "instruction": "Arrive at your destination.",
                                "travelTime": 0,
                                "length": 0,
                                "id": "M2",
                                "_type": "PrivateTransportManeuverType"
                            }
                        ]
                    }
                ],
                "note": [
                    {
                        "type": "violation",
                        "code": "routingOptionViolated",
                        "text": "startDirection"
                    }
                ],
                "summary": {
                    "distance": 0,
                    "trafficTime": 0,
                    "baseTime": 0,
                    "flags": [
                        "tollroad"
                    ],
                    "text": "The trip takes <span class=\"length\">0 m</span> and less than <span class=\"time\">1 min</span>.",
                    "travelTime": 0,
                    "_type": "RouteSummaryType"
                }
            }
        ],
        "language": "en-us"
    }
}

But the shape returned in the response doesn't seem to be the shape of the link, even though the developer guide mentions that the parameter "linkAttributes" can be used to get the link shape.

Please advise if I am doing anything wrong here. Also, if I can use another API to get shape of a link.

I am fine with making an API call per link_id.

Answer 1

A waypoint is used to define the locations on the map that the route must go through. A waypoint can be either a StopOver (for example, start or destination) or a PassThrough. A valid CalculateRoute request must include at least two StopOver waypoints. There are three ways to assign waypoints for the route

1. a rough position: GeoWaypointParameterType
2. a reference to a street: NavigationWaypointParameter with StreetPositions
3. an exact reference to a link: NavigationWaypointParameter with LinkPositions

The details can be found here: https://developer.here.com/documentation/routing/dev_guide/topics/resource-param-type-waypoint.html#resource-param-type-waypoint__geo-waypoint

Let me focus on 3rd point since you are using Link positions. Please note that the NavigationWaypointParameter defines a waypoint by LinkId and optional Spot value. Spot is defined as the fractional distance from the link's reference-node to the non-reference node, with a value between 0 and 1. When no Spot value nor DisplayPosition is given in request then default value 0.5 is assumed

The optional display position of the waypoint defines where the location is displayed on a map. It denotes the center of the location and is not navigable, it is not located on a link in the routing network in contrast to the navigation positions of a location. The display position allows the routing engine to decide whether the waypoint is located on the left or on the right-hand side of the route.

Here is the example from the documentation:

// using exact link information with display position and spot:
&waypoint0=link!37.7914050,-122.3987030!-743460791,0.8996

// using exact link information with display position and spot and additional stopover delay of 5 minutes:
&waypoint0=link!stopOver,300!37.7914050,-122.3987030!-743460791,0.8996

// the display position is optional:
&waypoint0=link!!-743460795,0.1342
&waypoint0=link!-743460795,0.1342

// using user label:
&waypoint0=link!37.7914050,-122.3987030;My Home!-743460791,0.8996

// using user label without display position:
&waypoint1=link!;My Work!-743460795

// link traveled in any direction:
&waypoint0=link!*743460795

Since the link parameter in the request is same for waypoint 0 and waypoint 1, only the point is returned. However, if you set spot for example, the link will be shown as below: https://refclient.ext.here.com/#url=https://route.api.here.com/routing/7.2/calculateroute.json?routeattributes=sh,gr&mode=fastest;car&maneuverattributes=po,ti,pt,ac,di,fj,ix&language=en-us&jsonattributes=41&metricsystem=metric&waypoint0=link!stopOver!-893783351,0.1342&waypoint1=link!stopOver!-893783351&app_code=kg72HCGA7Um5GdCdXRp5mw&app_id=wkkI0nFlieJAZT1KrbpW

But if you are looking for details specific to the link ID, you can use PDE request as explained here: https://tcs.ext.here.com/examples/v3/pde_get_any_link_info