Junction preview v2

Important Note
Explore ready-to-use traffic reports and data visualizations immediately by signing up for a 30-day free trial on the MOVE Portal. Once registered, you'll receive an API key to start using the Traffic Analytics APIs right away. Alternatively, you may contact our Sales team for a tailored solution.

Beta Version
This endpoint is currently in beta. The request and response definitions may change in future releases. We recommend using this endpoint for evaluation and testing purposes. Please refer to the latest documentation for any updates.

Purpose

Junction preview v2 is a REST API endpoint that allows users to review and verify a junction definition based on user-provided approach and exit geometries, before committing it as an active junction. This endpoint does not create a new junction.

Unlike the v1 preview endpoint which accepts a GeoJSON area (polygon or circle), the v2 endpoint accepts explicit approach and exit line geometries (userPoints) along with optional arrival points. The system routes each leg on the road network and returns the resolved junction model, including per-element status indicating whether each approach and exit was successfully matched.

The response contains the junction name, resolved approaches, exits, arrival points, element-level status, and other static details of the junction.

Request data

You can preview a junction by sending a POST request, as shown in the following example.

• Constants and parameters enclosed in curly brackets must be replaced with their values.
• Please see the following Request parameters section with the required and optional parameter tables for their values. The generic request format is as follows.

HTTPS method: POST

https://api.tomtom.com/junction-analytics/junctions/2/preview?key={Your_API_Key}

To preview changes for an existing junction, append the junction ID to the URL:

https://api.tomtom.com/junction-analytics/junctions/2/preview/{junctionId}?key={Your_API_Key}

POST request body example

1{
2  "junction": {
3    "name": "Test junction Amsterdam",
4    "externalId": "test-001"
5  },
6  "approaches": [
7    {
8      "externalId": "approach-001",
9      "name": "Approach N",
10      "params": {
11        "length": 200
12      },
13      "userPoints": {
14        "type": "LineString",
15        "coordinates": [
16          [4.7609263, 52.5004168],
17          [4.7617657, 52.5017972]
18        ]
19      },
20      "arrivalPoints": [
21        {
22          "externalId": "ap-001",
23          "name": "AP North",
24          "userPoint": {
25            "type": "Point",
26            "coordinates": [4.7617657, 52.5017972]
27          }
28        }
29      ]
30    }
31  ],
32  "exits": [
33    {
34      "externalId": "exit-001",
35      "name": "Exit S",
36      "params": {
37        "length": 180
38      },
39      "userPoints": {
40        "type": "LineString",
41        "coordinates": [
42          [4.7618271, 52.5018408],
43          [4.7630857, 52.5015000]
44        ]
45      }
46    }
47  ]
48}

Request parameters

The following table shows the query parameters:

• Required parameters must be used or the call will fail.
• Optional parameters may be used.

POST request body fields

junction (object) Required. Contains the junction-level metadata.

• junction.name (string) Name for the junction. Maximum length is 250 characters.
• junction.externalId (string) An optional external identifier for the junction. Maximum length is 250 characters.

approaches[] (array) Required. Contains junction approaches. Minimum number of approaches: 1. Maximum: 20.

• externalId (string) An optional external identifier for the approach. Maximum length is 250 characters.
• name (string) An optional display name for the approach.
• params (object) Optional parameters for the approach.
  • params.length (integer) Expected length of the approach in meters. Used for validation — the system will flag a mismatch if the routed length deviates more than 30% from this value.
• userPoints (object) Required. A GeoJSON LineString defining the approach geometry. The system routes along the road network through these coordinates. See the GeoJSON LineString specification.
• arrivalPoints[] (array) Contains arrival points for the approach. Maximum number of arrival points: 3.
  • externalId (string) An optional external identifier for the arrival point. Maximum length is 250 characters.
  • name (string) An optional name for the arrival point.
  • userPoint (object) Required. A GeoJSON Point defining the arrival point location. See the GeoJSON Point specification.

exits[] (array) Required. Contains junction exits. Minimum number of exits: 1. Maximum: 20.

• externalId (string) An optional external identifier for the exit. Maximum length is 250 characters.
• name (string) An optional display name for the exit.
• params (object) Optional parameters for the exit.
  • params.length (integer) Expected length of the exit in meters. Used for validation — the system will flag a mismatch if the routed length deviates more than 30% from this value.
• userPoints (object) Required. A GeoJSON LineString defining the exit geometry. The system routes along the road network through these coordinates. See the GeoJSON LineString specification.

Request headers

Example request

The following is an example curl request:

1$ curl 'https://api.tomtom.com/junction-analytics/junctions/2/preview?key={Your_API_Key}' -i -X POST \
2  -H 'Content-Type: application/json' \
3  -d '{
4  "junction": {
5    "name": "Test junction Amsterdam",
6    "externalId": "test-001"
7  },
8  "approaches": [
9    {
10      "externalId": "approach-001",
11      "name": "Approach N",
12      "params": {
13        "length": 200
14      },
15      "userPoints": {
16        "type": "LineString",
17        "coordinates": [
18          [4.7609263, 52.5004168],
19          [4.7617657, 52.5017972]
20        ]
21      },
22      "arrivalPoints": [
23        {
24          "externalId": "ap-001",
25          "name": "AP North",
26          "userPoint": {
27            "type": "Point",
28            "coordinates": [4.7617657, 52.5017972]
29          }
30        }
31      ]
32    }
33  ],
34  "exits": [
35    {
36      "externalId": "exit-001",
37      "name": "Exit S",
38      "params": {
39        "length": 180
40      },
41      "userPoints": {
42        "type": "LineString",
43        "coordinates": [
44          [4.7618271, 52.5018408],
45          [4.7630857, 52.5015000]
46        ]
47      }
48    }
49  ]
50}'

Response data

This response returns the junction preview details, including the resolved junction model and per-element status.

Example response

The following JSON code block is an example response:

1{
2  "externalId": "test-001",
3  "name": "Test junction Amsterdam",
4  "status": "PREVIEW",
5  "rawJunction": {
6    "name": "Test junction Amsterdam",
7    "externalId": "test-001",
8    "approaches": [
9      {
10        "externalId": "approach-001",
11        "name": "Approach N",
12        "userPoints": {
13          "type": "LineString",
14          "coordinates": [
15            [4.7609263, 52.5004168],
16            [4.7617657, 52.5017972]
17          ]
18        },
19        "arrivalPoints": [
20          {
21            "externalId": "ap-001",
22            "name": "AP North",
23            "userPoint": {
24              "type": "Point",
25              "coordinates": [4.7617657, 52.5017972]
26            }
27          }
28        ]
29      }
30    ],
31    "exits": [
32      {
33        "externalId": "exit-001",
34        "name": "Exit S",
35        "userPoints": {
36          "type": "LineString",
37          "coordinates": [
38            [4.7618271, 52.5018408],
39            [4.7630857, 52.5015]
40          ]
41        }
42      }
43    ]
44  },
45  "junctionModel": {
46    "name": "Test junction Amsterdam",
47    "countryCode": "NLD",
48    "driveOnLeft": false,
49    "trafficLights": false,
50    "approaches": [
51      {
52        "externalId": "approach-001",
53        "name": "Fortuinlaan North Bound",
54        "roadName": "Fortuinlaan",
55        "direction": "NORTH",
56        "frc": 6,
57        "length": 174.18,
58        "oneWayRoad": false,
59        "excluded": false,
60        "drivable": true,
61        "segmentedGeometry": {
62          "type": "MultiLineString",
63          "coordinates": [
64            [[4.76084, 52.50038], [4.76106, 52.5007]],
65            [[4.76106, 52.5007], [4.76118, 52.5009]],
66            [[4.76118, 52.5009], [4.76178, 52.50184]]
67          ]
68        },
69        "openlr": "CwNisCVVaDPCAgBeAJIzEQ==",
70        "dataNotAvailable": false,
71        "arrivalPoints": [
72          {
73            "externalId": "ap-001",
74            "name": "AP North",
75            "projectedPoint": {
76              "type": "Point",
77              "coordinates": [4.761756449662269, 52.50180310447089]
78            }
79          }
80        ]
81      }
82    ],
83    "exits": [
84      {
85        "externalId": "exit-001",
86        "name": "Heiligeweg East Bound",
87        "roadName": "Heiligeweg",
88        "direction": "EAST",
89        "frc": 6,
90        "oneWayRoad": false,
91        "drivable": true,
92        "segmentedGeometry": {
93          "type": "MultiLineString",
94          "coordinates": [
95            [[4.76178, 52.50184], [4.76182, 52.50182], [4.76297, 52.50155]]
96          ]
97        },
98        "openlr": "CwNi3CVVrDPKAQB3/+MzGQ=="
99      }
100    ]
101  },
102  "elementsStatus": [
103    {
104      "externalId": "exit-001",
105      "type": "EXIT",
106      "status": "FAILED",
107      "error": {
108        "code": "ROUTING_LENGTH_MISMATCH",
109        "message": "Routed length deviates more than 30% from the expected length.",
110        "hint": "Verify that the params.length value matches the actual road distance."
111      }
112    },
113    {
114      "externalId": "approach-001",
115      "type": "APPROACH",
116      "status": "OK"
117    }
118  ]
119}

Response fields

The following section describes all of the fields that can appear in a response.

externalId (string) The external identifier provided in the request, if any.

name (string) The name of the junction as provided in the request.

status (string) The status of the junction. For preview responses, the value is always PREVIEW.

rawJunction (object) An echo of the original request data.

• rawJunction.name (string) The junction name as provided in the request.
• rawJunction.externalId (string) The external identifier as provided in the request.
• rawJunction.approaches[] (array) The approaches as provided in the request.
  • externalId (string) The external identifier of the approach.
  • name (string) The name of the approach.
  • userPoints (object) The GeoJSON LineString as provided in the request.
  • arrivalPoints[] (array) The arrival points as provided in the request.
    • externalId (string) The external identifier of the arrival point.
    • name (string) The name of the arrival point.
    • userPoint (object) The GeoJSON Point as provided in the request.
• rawJunction.exits[] (array) The exits as provided in the request.
  • externalId (string) The external identifier of the exit.
  • name (string) The name of the exit.
  • userPoints (object) The GeoJSON LineString as provided in the request.

junctionModel (object) The resolved junction model generated by the system.

• name (string) The name of the junction.
• countryCode (string) The three-letter country code defined in the ISO 3166-1 alpha-3 standard.
• driveOnLeft (boolean) Flag indicating left-hand traffic (LHT) or right-hand traffic (RHT).
• trafficLights (boolean) true if traffic lights are detected inside the junction area.
• approaches[] (array) Contains the resolved junction approaches.
  • externalId (string) The external identifier of the approach, if provided.
  • name (string) Created based on the road name and direction. Example: "Fortuinlaan North Bound".
  • roadName (string) If the road has no name, it will be "Unnamed road".
  • direction (string) One of the following values: SOUTH, WEST, EAST, NORTH, CLOCKWISE, COUNTER_CLOCKWISE.
  • frc (integer) Functional Road Class. One of the values: 0, 1, 2, 3, 4, 5, 6, 7.
  • length (float) Length of the given approach in meters.
  • oneWayRoad (boolean) true if it is a one-direction road or not a single carriageway road.
  • excluded (boolean) Indicates whether live data collection for the approach is excluded.
  • drivable (boolean) Indicates if the road is drivable.
  • segmentedGeometry (object) Geometry of the given approach, split by map segments. See the GeoJSON MultiLineString specification.
  • openlr (string) Geometry of the given approach, encoded into OpenLR format. See the OpenLR specification.
  • dataNotAvailable (boolean) Indicates whether data is available for this approach.
  • arrivalPoints[] (array) Contains the resolved arrival points.
    • externalId (string) The external identifier of the arrival point, if provided.
    • name (string) The name of the arrival point.
    • projectedPoint (object) The projected point on the road network. See the GeoJSON Point specification.
• exits[] (array) Contains the resolved junction exits.
  • externalId (string) The external identifier of the exit, if provided.
  • name (string) Created based on the road name and direction. Example: "Heiligeweg East Bound".
  • roadName (string) If the road has no name, it will be "Unnamed road".
  • direction (string) One of the values: SOUTH, WEST, EAST, NORTH, CLOCKWISE, COUNTER_CLOCKWISE.
  • frc (integer) Functional Road Class. One of the values: 0, 1, 2, 3, 4, 5, 6, 7.
  • oneWayRoad (boolean) true if it is a one-direction road or not a single carriageway road.
  • drivable (boolean) Indicates if the road is drivable.
  • segmentedGeometry (object) Geometry of the given exit, split by map segments. See the GeoJSON MultiLineString specification.
  • openlr (string) Geometry of the given exit, encoded into OpenLR format. See the OpenLR specification.

elementsStatus[] (array) Contains the per-element validation status for each approach and exit.

• externalId (string) The external identifier of the element.
• type (string) The element type: APPROACH or EXIT.
• status (string) The validation status: OK or FAILED.
• error (object) Present only when status is FAILED.
  • error.code (string) A machine-readable error code (e.g., ROUTING_LENGTH_MISMATCH).
  • error.message (string) A human-readable error description.
  • error.hint (string) A suggestion for resolving the issue.

Errors

The system generates an error response if there is an error in the supplied parameters or any other internal problem. This response is generated in the requested format.

Error response codes

The following table shows the HTTP error response codes.

Error response field

Example error response

The following is an example error response:

1{
2  "message": "At least 1 approach is required."
3}