Junction manual creation

Service version: v1 Last edit: 2025.02.25

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.

Enhanced Junction Analytics Users If the Enhanced Junction Analytics option is active on your account, by default, the system will automatically add predefined arrival points if you choose not to specify your own. If you prefer to configure custom arrival points, you can do so by utilizing the designated endpoint.

Purpose

The Junction Manual Creation is a specialized REST API endpoint designed to provide a customized way to create junctions. Through this endpoint, users can manually define the properties of the junction.

Features

Selective Approaches: The endpoint supports the deactivation of approaches that are not required by the customer.

Workflow

Junction Definition Preview:
- Before proceeding with the manual creation of the junction, utilize the Junction Definition Preview to visualize and review the proposed junction.
Prepare Request:
- The response from the Junction Definition Preview contains essential fields (junction, approaches, exits) that should be included in the Junction Definition Manual Creation request.
Receive Response:
- Upon successful submission, the response will provide a unique junction ID.

Request data

To manually create the junction, issue a POST request as demonstrated in the following example. Ensure you adhere to the specified request format for successful updates.

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

1
https://api.tomtom.com/junction-analytics/junctions/1/definition/manual?key={Your_API_Key}

POST request body example

post

POST request body example - JSON

1
{
2
    "name": "Otto-Braun-Straße - Karl-Marx-Allee - Alexanderstraße",
3
    "detectionConfig": {
4
        "autodetectName": true
5
    },
6
    "junction": {
7
        "type": "Feature",
8
        "geometry": {
9
            "type": "Point",
10
            "coordinates": [
11
                13.41649420385599,
12
                52.52202006909155
13
            ]
14
        },
15
        "properties": {
16
            "radius": 51.30814890800801
17
        }
18
    },
19
    "approaches": [
20
        {
21
            "id": -1194621510,
22
            "segmentedGeometry": {
23
                "type": "MultiLineString",
24
                "coordinates": [
25
                    [
26
                        [
27
                            13.41808,
28
                            52.52377
29
                        ],
30
                        [
31
                            13.41775,
32
                            52.52348
33
                        ]
34
                    ],
35
                    [
36
                        [
37
                            13.41775,
38
                            52.52348
39
                        ],
40
                        [
41
                            13.41704,
42
                            52.52285
43
                        ]
44
                    ]
45
                ]
46
            },
47
            "excluded": false
48
        },
49
        {
50
            "id": 1275645260,
51
            "segmentedGeometry": {
52
                "type": "MultiLineString",
53
                "coordinates": [
54
                    [
55
                        [
56
                            13.41958,
57
                            52.5212
58
                        ],
59
                        [
60
                            13.41889,
61
                            52.52141
62
                        ]
63
                    ],
64
                    [
65
                        [
66
                            13.41889,
67
                            52.52141
68
                        ],
69
                        [
70
                            13.41871,
71
                            52.52146
72
                        ]
73
                    ]
74
                ]
75
            },
76
            "excluded": false
77
        }
78
    ],
79
    "exits": [
80
        {
81
            "segmentedGeometry": {
82
                "type": "MultiLineString",
83
                "coordinates": [
84
                    [
85
                        [
86
                            13.41599,
87
                            52.52178
88
                        ],
89
                        [
90
                            13.41576,
91
                            52.52155
92
                        ]
93
                    ]
94
                ]
95
            }
96
        },
97
        {
98
            "segmentedGeometry": {
99
                "type": "MultiLineString",
100
                "coordinates": [
101
                    [
102
                        [
103
                            13.41641,
104
                            52.52223
105
                        ],
106
                        [
107
                            13.41625,
108
                            52.5223
109
                        ]
110
                    ]
111
                ]
112
            }
113
        }
114
    ]
115
}

POST request body example for enhanced access enabled

Request body - JSON

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

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 parameters	Description
`key` string	An API Key valid for the requested service. Value: Your valid API Key.

POST request body fields

name (string) Name for a newly created junction. Not required by default. Take a look at detectionConfig.autodetectName. Maximum length is 250 characters.

detectionConfig (object) Contains the detection configuration used in junction creation.

autodetectName (boolean) If true, the junction name will be created based on its approaches. If false, the name field is required. Default value: true

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.

GeoJSON Polygon specification
- Requirements: an area size smaller then 1km² and a boundary smaller than 3km.
GeoJSON Point specification
- Requirements: a radius smaller than 500m.

exits[] (array) Contains junction exits. Minimum numbers of exits: 1. The details in this section are derived from the Junction Definition Preview .

segmentedGeometry (object) Geometry of the given exit, split by map segments. See the GeoJSON MultiLineString specification .

approaches[] (array) Contains junction approaches. Minimum number of approaches: 1. The details in this section are derived from the Junction Definition Preview .

id (integer) The approach ID is unique in the junction context.
excluded (boolean) Indicates that live data for the approach is collected.
segmentedGeometry (object) Geometry of the given approach, split by map segments. See the GeoJSON MultiLineString specification .
arrivalPoints[] (array) Applicable only for Enhanced Junction Analytics users 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 .

Request headers

Header	Value
Content-Type	`application/json`

Example request

The following is an example curl request:

post

curl command example

1
$ curl 'https://api.tomtom.com/junction-analytics/junctions/1/definition/manual?key={Your_API_Key}' -i -X POST -d '{
2
    "name": "Otto-Braun-Straße - Karl-Marx-Allee - Alexanderstraße",
3
    "detectionConfig": {
4
        "autodetectName": true
5
    },
6
    "junction": {
7
        "type": "Feature",
8
        "geometry": {
9
            "type": "Point",
10
            "coordinates": [
11
                13.41649420385599,
12
                52.52202006909155
13
            ]
14
        },
15
        "properties": {
16
            "radius": 51.30814890800801
17
        }
18
    },
19
    "approaches": [
20
        {
21
            "id": -1194621510,
22
            "segmentedGeometry": {
23
                "type": "MultiLineString",
24
                "coordinates": [
25
                    [
26
                        [
27
                            13.41808,
28
                            52.52377
29
                        ],
30
                        [
31
                            13.41775,
32
                            52.52348
33
                        ]
34
                    ],
35
                    [
36
                        [
37
                            13.41775,
38
                            52.52348
39
                        ],
40
                        [
41
                            13.41704,
42
                            52.52285
43
                        ]
44
                    ]
45
                ]
46
            },
47
            "excluded": false
48
        },
49
        {
50
            "id": 1275645260,
51
            "segmentedGeometry": {
52
                "type": "MultiLineString",
53
                "coordinates": [
54
                    [
55
                        [
56
                            13.41958,
57
                            52.5212
58
                        ],
59
                        [
60
                            13.41889,
61
                            52.52141
62
                        ]
63
                    ],
64
                    [
65
                        [
66
                            13.41889,
67
                            52.52141
68
                        ],
69
                        [
70
                            13.41871,
71
                            52.52146
72
                        ]
73
                    ]
74
                ]
75
            },
76
            "excluded": false
77
        }
78
    ],
79
    "exits": [
80
        {
81
            "segmentedGeometry": {
82
                "type": "MultiLineString",
83
                "coordinates": [
84
                    [
85
                        [
86
                            13.41599,
87
                            52.52178
88
                        ],
89
                        [
90
                            13.41576,
91
                            52.52155
92
                        ]
93
                    ]
94
                ]
95
            }
96
        },
97
        {
98
            "segmentedGeometry": {
99
                "type": "MultiLineString",
100
                "coordinates": [
101
                    [
102
                        [
103
                            13.41641,
104
                            52.52223
105
                        ],
106
                        [
107
                            13.41625,
108
                            52.5223
109
                        ]
110
                    ]
111
                ]
112
            }
113
        }
114
    ]
115
}'

Response data

This response returns the junction ID and modification type.

Example response

The following JSON code block is an example response:

Response body - JSON

1
{
2
    "modificationType": "Created",
3
    "junctionId": "65268ff77cd5d952a185b9b5"
4
}

Response fields

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

modificationType (string) String that describes the modification type. In this case it has value Created.

junctionId (string) Unique ID of the created junction.

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.

Code	Description
401	Unauthorized
403	Forbidden
400	Bad Request Example messages: Junctions limit of 10 is reached. Remove some of your existing junctions or contact support. ‘junction’ field is required. Name should be provided if detectionConfig.autodetectName is set to false! Name should not be empty or consist of only whitespace! Junction name TestJunction exceeded maximum length of 250. We’re having trouble creating the junction. This issue is noted in the system, please try later. Maximum area of 1 km² 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.

Code

Description

401

Unauthorized

403

Forbidden

400

Bad Request Example messages:

Junctions limit of 10 is reached. Remove some of your existing junctions or contact support.
‘junction’ field is required.
Name should be provided if detectionConfig.autodetectName is set to false!
Name should not be empty or consist of only whitespace!
Junction name TestJunction exceeded maximum length of 250.
We’re having trouble creating the junction. This issue is noted in the system, please try later.
Maximum area of 1 km² 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

Field	Description
`message` string	The problem description.

Example error response

The following is an example error response:

Response error message - JSON

1
{
2
  "message": "Name should be provided if detectionConfig.autodetectName is set to false!"
3
}

Junction manual creation

Purpose

Features

Workflow

Request data

HTTPS method: POST

POST request body example

POST request body example for enhanced access enabled

Request parameters

POST request body fields

Request headers

Example request

Response data

Example response

Response fields

Errors

Error response codes

Error response field

Example error response

HTTPS method: `POST`