Developer

Junction preview

Service version: v1
Last edit: 2025.03.28
Try 30 Days Free

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.

Purpose

Junction preview is a REST API endpoint that allows users to review and verify the generated junction based on the provided area. This endpoint does not create a new Junction.

The response contains the name, approaches, exits, and other static details of the junction.

Request data

You can preview the 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

post
URL request example
https://api.tomtom.com/junction-analytics/junctions/1/preview?key={Your_API_Key}

POST request body example

post
POST request body example - JSON
1{
2    "junction": {
3        "type": "Feature",
4        "properties": {},
5        "geometry": {
6            "type": "Polygon",
7            "coordinates": [
8                [
9                    [
10                        19.45177674293518,
11                        51.776719390207354
12                    ],
13                    [
14                        19.45182502269745,
15                        51.77639411588313
16                    ],
17                    [
18                        19.45253312587738,
19                        51.77646049858872
20                    ],
21                    [
22                        19.45253312587738,
23                        51.776792410651765
24                    ],
25                    [
26                        19.45177674293518,
27                        51.776719390207354
28                    ]
29                ]
30            ]
31        }
32    }, 
33}

POST request body example for enhanced access enabled

post
POST request body example for enhanced access enabled - JSON
1{
2    "junction": {
3        "type": "Feature",
4        "properties": {},
5        "geometry": {
6            "type": "Polygon",
7            "coordinates": [
8                [
9                    [
10                        19.45177674293518,
11                        51.776719390207354
12                    ],
13                    [
14                        19.45182502269745,
15                        51.77639411588313
16                    ],
17                    [
18                        19.45253312587738,
19                        51.77646049858872
20                    ],
21                    [
22                        19.45253312587738,
23                        51.776792410651765
24                    ],
25                    [
26                        19.45177674293518,
27                        51.776719390207354
28                    ]
29                ]
30            ]
31        }
32    },
33        "detectionConfig" : {
34            "withDefaultArrivals": true
35        }
36}

Request parameters

The following table shows the query parameters:

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

key
string

An API Key valid for the requested service. Value: Your valid API Key.

Post request body fields

junction (object) Required. A GeoJSON Feature, Polygon, or Point (with the radius property). It contains the junction boundary that will be used in the creation process.

detectionConfig (object) Contains the detection configuration used in the junction preview. This parameter is applicable only for Enhanced Junction Analytics users

  • detectionConfig.withDefaultArrivals (boolean) When set to true, the preview includes default arrival points. If set to false, default arrival points are excluded. The default value is false.

Request headers

HeaderValue
Content-Typeapplication/json

Example request

The following is an example curl request with polygon:

post
curl command example
1$ curl '/junction-analytics/junctions/1/definition/auto?key={Your_API_Key}' -i -X POST -d '{
2    "junction": {
3        "type": "Feature",
4        "properties": {},
5        "geometry": {
6            "type": "Polygon",
7            "coordinates": [
8                [
9                    [
10                        19.45177674293518,
11                        51.776719390207354
12                    ],
13                    [
14                        19.45182502269745,
15                        51.77639411588313
16                    ],
17                    [
18                        19.45253312587738,
19                        51.77646049858872
20                    ],
21                    [
22                        19.45253312587738,
23                        51.776792410651765
24                    ],
25                    [
26                        19.45177674293518,
27                        51.776719390207354
28                    ]
29                ]
30            ]
31        }
32    }
33}'

The following is an example curl request with circle:

post
curl command example
1$ curl '/junction-analytics/junctions/1/definition/auto?key={Your_API_Key}' -i -X POST -d '{
2    "junction": {
3        "type": "Feature",
4        "geometry": {
5            "type": "Point",
6            "coordinates": [
7                13.41649420385599,
8                52.52202006909155
9            ]
10        },
11        "properties": {
12            "radius": 51.30
13        }
14    }
15}'

Response data

This response returns junction preview details.

Example response

The following JSON code block is an example response:

Response body - JSON
1{
2    "name": "First Street - Second Street",
3    "countryCode": "DEU",
4    "driveOnLeft": false,
5    "trafficLights": true,
6    "approaches": [
7      {
8        "id": 1397964518,
9        "name": "First Street West Bound",
10        "roadName": "First Street",
11        "direction": "WEST",
12        "frc": 7,
13        "length": 192.77,
14        "oneWayRoad": false,
15        "excluded": false,
16        "drivable": true,
17        "segmentedGeometry": {
18          "type": "MultiLineString",
19          "coordinates": [
20            [
21              [19.45464, 51.77712],
22              [19.45452, 51.77711],
23              [19.45443, 51.77708]
24            ]
25          ]
26        }
27      },
28      {
29        "id": -2036692957,
30        "name": "Second Street North Bound",
31        "roadName": "Second Street",
32        "direction": "NORTH",
33        "frc": 4,
34        "length": 236.16,
35        "oneWayRoad": true,
36        "excluded": false,
37        "drivable": true,
38        "segmentedGeometry": {
39          "type": "MultiLineString",
40          "coordinates": [
41            [
42              [19.45265, 51.77446],
43              [19.45224, 51.77653],
44              [19.45224, 51.77657]
45            ]
46          ]
47        }
48      }
49    ],
50    "exits": [
51      {
52        "id": 2032081462,
53        "name": "First Street North Bound",
54        "roadName": "First Street",
55        "direction": "NORTH",
56        "frc": 4,
57        "oneWayRoad": false,
58        "drivable": true,
59        "segmentedGeometry": {
60          "type": "MultiLineString",
61          "coordinates": [
62            [
63              [19.45224, 51.77657],
64              [19.45222, 51.77665]
65            ]
66          ]
67        }
68      },
69      {
70        "id": -351401112,
71        "name": "Second Street East Bound",
72        "roadName": "Second Street",
73        "direction": "EAST",
74        "frc": 7,
75        "oneWayRoad": false,
76        "drivable": true,
77        "segmentedGeometry": {
78          "type": "MultiLineString",
79          "coordinates": [
80            [
81              [19.45224, 51.77657],
82              [19.4525, 51.77659]
83            ]
84          ]
85        }
86      }
87    ]
88}

Example response for enhanced access enabled

The following JSON code block is an example response when enhanced access is enabled:

Response body - JSON
1{
2    "name": "First Street- Second street",
3    "countryCode": "USA",
4    "driveOnLeft": false,
5    "trafficLights": true,
6    "approaches": [
7        {
8            "id": -1820173215,
9            "name": "First Street West Bound",
10            "roadName": "First Street",
11            "direction": "WEST",
12            "frc": 4,
13            "length": 242.3,
14            "oneWayRoad": true,
15            "excluded": false,
16            "drivable": true,
17            "segmentedGeometry": {
18                "type": "MultiLineString",
19                "coordinates": [
20                    [
21                        [
22                            -122.01619,
23                            37.94464
24                        ],
25                        [
26                            -122.01628,
27                            37.94458
28                        ],
29                        [
30                            -122.01725,
31                            37.94392
32                        ]
33                    ],
34                    [
35                        [
36                            -122.01725,
37                            37.94392
38                        ],
39                        [
40                            -122.01828,
41                            37.94323
42                        ]
43                    ]
44                ]
45            },
46            "arrivalPoints": [
47                {
48                    "id": 0,
49                    "name": "stop line",
50                    "userPoint": {
51                        "type": "Point",
52                        "coordinates": [
53                            -122.01828,
54                            37.94323000000001
55                        ]
56                    },
57                    "projectedPoint": {
58                        "type": "Point",
59                        "coordinates": [
60                            -122.01828,
61                            37.94323000000001
62                        ]
63                    }
64                },
65                {
66                    "id": 12,
67                    "name": "40ft",
68                    "userPoint": {
69                        "type": "Point",
70                        "coordinates": [
71                            -122.01817410432558,
72                            37.94330094083544
73                        ]
74                    },
75                    "projectedPoint": {
76                        "type": "Point",
77                        "coordinates": [
78                            -122.01817410432558,
79                            37.94330094083544
80                        ]
81                    }
82                },
83                {
84                    "id": 106,
85                    "name": "350ft",
86                    "userPoint": {
87                        "type": "Point",
88                        "coordinates": [
89                            -122.01735340594522,
90                            37.943850729049636
91                        ]
92                    },
93                    "projectedPoint": {
94                        "type": "Point",
95                        "coordinates": [
96                            -122.01735340594522,
97                            37.943850729049636
98                        ]
99                    }
100                }
101            ]
102        }
103    ],
104    "exits": [
105        {
106            "id": 1474468109,
107            "name": "Second Street East Bound",
108            "roadName": "Second Street",
109            "direction": "EAST",
110            "frc": 4,
111            "oneWayRoad": true,
112            "drivable": true,
113            "segmentedGeometry": {
114                "type": "MultiLineString",
115                "coordinates": [
116                    [
117                        [
118                            -122.01818,
119                            37.94313
120                        ],
121                        [
122                            -122.01761,
123                            37.94352
124                        ]
125                    ]
126                ]
127            }
128        }
129    ]
130}

Response fields

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

name (string) The name of the junction as generated automatically, or provided in the junction definition creation request.

countryCode (string) The three-letter country code defined in the ISO 3166-1 alpha-3 standard.

driveOnLeft (boolean) This is a flag with information about left-hand traffic (LHT) or right-hand traffic (RHT).

trafficLights (boolean) This is true if traffic lights are inside the creation area.

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

  • id (integer) The approach ID is unique in the junction context.
  • name (string) Created based on the name and road direction. Example: "Some Street West 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) It is true if it is a one-direction road or not a single carriageway road.
  • excluded (boolean) Indicates that live data for the approach is collected.
  • drivable (boolean) Indicates if the road is drivable.
  • segmentedGeometry (object) Geometry of the given approach, split by map segments. See the GeoJSON MultiLineString specification.
  • userPoints (array) Array of user-defined points that the geometry routes through. See the GeoJSON Point specification.
  • openlr (string) Geometry of given approach, encoded into OpenLR format. See the OpenLR specification.
  • arrivalPoints [] (array) Applicable only for Enhanced Junction Analytics users and withDefaultArrivals is true Contains arrival points for approaches. Maximum number of arrival points: 3.
    • id (integer) The arrival point ID is unique in the approach context.
    • name (string) Name for an arrival Point.
    • userPoint Coordinates of point that the geometry routes through. See the GeoJSON Point specification.
    • projectedPoint Coordinates of point that the geometry routes through. See the GeoJSON Point specification.

exits[] (array) Contains junction exits. Minimum numbers of exits: 1.

  • id (integer) The exit ID is unique in the junction context.
  • name (string) This is created based on the name and road direction. Example: "Typical Street West 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) It is 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.

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.

CodeDescription
401

Unauthorized

403

Forbidden

400

Bad Request Example messages:

  • We're having trouble creating the junction. This issue is noted in the system, please try later.
  • Maximum area of 1 km2 exceeded.
  • Maximum area boundary length of 3000 meters exceeded.
  • Maximum radius of 500 meters exceeded.
  • Circle radius can't be empty.
  • A junction that crosses countries is unsupported; attempted POL, DEU.

Error response field

FieldDescription

message
string

The problem description.

Example error response

The following is an example error response:

Response error message - JSON
1{
2  "message": "Circle radius can't be empty"
3}