Developer

Junction manual creation v2

Service version: v2
Beta
Last edit: 2026.05.25
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.

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

The Junction Manual Creation v2 is a REST API endpoint designed to create junctions by providing explicit approach and exit geometries.

Unlike v1, which requires a GeoJSON area (polygon or circle) and approach/exit data from a prior preview response, v2 allows users to define approach and exit legs directly via GeoJSON LineString geometries (userPoints), along with optional arrival points. The system routes each leg on the road network and creates the junction.

Key differences from v1

  • Geometry-based definition: Instead of providing a junction area boundary and referencing preview-generated segmentedGeometry, you supply userPoints (GeoJSON LineString) for each approach and exit. The system handles road-network routing internally.

  • External identifiers: Approaches, exits, arrival points, and the junction itself support optional externalId fields for integration with external systems.

  • Element-level status: The response includes an elementsStatus array that reports the validation status (OK or FAILED) for each approach and exit, along with error details and hints when applicable.

  • Rich response: The creation response returns the full junction definition (including the resolved junction model), rather than just the junction ID.

Workflow

  1. Junction Definition Preview (recommended):

    • Before proceeding with manual creation, utilize the Junction Definition Preview v2 to visualize and verify the resolved junction model. Review the elementsStatus to ensure all approaches and exits are matched correctly.

  2. Prepare Request:

    • Use the same request body format as the preview. Adjust approach/exit geometries and arrival points based on the preview feedback.

  3. Receive Response:

    • Upon successful submission, the response will provide the full junction definition including a unique junction ID, the resolved junction model, and per-element status.
    • If any approaches or exits have validation issues (e.g., routing length mismatch), the junction will not be saved and the API will return a 422 Unprocessable Entity response with a dry-run preview of the junction. To force creation despite element issues, set the forceCreate query parameter to true.

Request data

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

  • 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/2/definition/manual?key={Your_API_Key}&forceCreate={forceCreate}

POST request body example

post
POST request body example - JSON
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.
Required parametersDescription

key
string

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

Optional parametersDescription

forceCreate
boolean

When set to true, the junction will be created even if some approaches or exits have validation issues (e.g., routing length mismatch). Default value: false.

POST request body fields

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

  • junction.name (string) Name for a newly created 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

HeaderValue
Content-Typeapplication/json

Example request

The following is an example curl request:

post
curl command example
1$ curl 'https://api.tomtom.com/junction-analytics/junctions/2/definition/manual?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 endpoint can return two types of responses depending on the validation outcome:

  • 201 Created — The junction was successfully created. The response body contains the full junction definition.
  • 422 Unprocessable Entity — Some approaches or exits have validation issues (e.g., routing length mismatch). The junction was not saved. The response body contains a dry-run preview of the junction with element-level status. To create the junction despite these issues, retry the request with forceCreate=true.

Example response (201 Created)

The following JSON code block is an example response when the junction is successfully created:

Response body - JSON
1{
2  "modificationType": "Created",
3  "junction": {
4    "id": "6a03889547510ce415df787e",
5    "externalId": "test-001",
6    "name": "Test junction Amsterdam",
7    "status": "ACTIVE",
8    "rawJunction": {
9      "name": "Test junction Amsterdam",
10      "externalId": "test-001",
11      "approaches": [
12        {
13          "externalId": "approach-001",
14          "name": "Approach N",
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          "userPoints": {
39            "type": "LineString",
40            "coordinates": [
41              [4.7618271, 52.5018408],
42              [4.7630857, 52.5015]
43            ]
44          }
45        }
46      ]
47    },
48    "junctionModel": {
49      "name": "Test junction Amsterdam",
50      "countryCode": "NLD",
51      "driveOnLeft": false,
52      "trafficLights": false,
53      "approaches": [
54        {
55          "id": 2024246980,
56          "externalId": "approach-001",
57          "name": "Fortuinlaan North Bound",
58          "roadName": "Fortuinlaan",
59          "direction": "NORTH",
60          "frc": 6,
61          "length": 174.18,
62          "oneWayRoad": false,
63          "excluded": false,
64          "drivable": true,
65          "segmentedGeometry": {
66            "type": "MultiLineString",
67            "coordinates": [
68              [[4.76084, 52.50038], [4.76106, 52.5007]],
69              [[4.76106, 52.5007], [4.76118, 52.5009]],
70              [[4.76118, 52.5009], [4.76178, 52.50184]]
71            ]
72          },
73          "openlr": "CwNisCVVaDPCAgBeAJIzEQ==",
74          "dataNotAvailable": false,
75          "arrivalPoints": [
76            {
77              "id": 0,
78              "externalId": "ap-001",
79              "name": "AP North",
80              "projectedPoint": {
81                "type": "Point",
82                "coordinates": [4.761756449662269, 52.50180310447089]
83              }
84            }
85          ]
86        }
87      ],
88      "exits": [
89        {
90          "id": -1894591808,
91          "externalId": "exit-001",
92          "name": "Heiligeweg East Bound",
93          "roadName": "Heiligeweg",
94          "direction": "EAST",
95          "frc": 6,
96          "oneWayRoad": false,
97          "drivable": true,
98          "segmentedGeometry": {
99            "type": "MultiLineString",
100            "coordinates": [
101              [[4.76178, 52.50184], [4.76182, 52.50182], [4.76297, 52.50155]]
102            ]
103          },
104          "openlr": "CwNi3CVVrDPKAQB3/+MzGQ=="
105        }
106      ]
107    },
108    "elementsStatus": [
109      {
110        "externalId": "exit-001",
111        "type": "EXIT",
112        "status": "FAILED",
113        "error": {
114          "code": "ROUTING_LENGTH_MISMATCH",
115          "message": "Routed length deviates more than 30% from the expected length.",
116          "hint": "Verify that the params.length value matches the actual road distance."
117        }
118      },
119      {
120        "externalId": "approach-001",
121        "type": "APPROACH",
122        "status": "OK"
123      }
124    ],
125    "createdAt": "2026-05-12T20:07:49.008099503Z",
126    "lastModifiedAt": "2026-05-12T20:07:49.018949896Z",
127    "lastUserUpdatedAt": "2026-05-12T20:07:49.008099503Z",
128    "timeZone": "Europe/Amsterdam"
129  }
130}

Example response (422 Unprocessable Entity)

The following JSON code block is an example response when element validation issues prevent the junction from being saved:

Response body (422) - JSON
1{
2  "modificationType": "NotCreated",
3  "junction": {
4    "externalId": "test-001",
5    "name": "Test junction Amsterdam",
6    "rawJunction": {
7      "name": "Test junction Amsterdam",
8      "externalId": "test-001",
9      "approaches": [
10        {
11          "externalId": "approach-001",
12          "name": "Approach N",
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          "userPoints": {
37            "type": "LineString",
38            "coordinates": [
39              [4.7618271, 52.5018408],
40              [4.7630857, 52.5015]
41            ]
42          }
43        }
44      ]
45    },
46    "junctionModel": {
47      "name": "Test junction Amsterdam",
48      "countryCode": "NLD",
49      "driveOnLeft": false,
50      "trafficLights": false,
51      "approaches": [
52        {
53          "externalId": "approach-001",
54          "name": "Fortuinlaan North Bound",
55          "roadName": "Fortuinlaan",
56          "direction": "NORTH",
57          "frc": 6,
58          "length": 174.18,
59          "oneWayRoad": false,
60          "excluded": false,
61          "drivable": true,
62          "segmentedGeometry": {
63            "type": "MultiLineString",
64            "coordinates": [
65              [[4.76084, 52.50038], [4.76106, 52.5007]],
66              [[4.76106, 52.5007], [4.76118, 52.5009]],
67              [[4.76118, 52.5009], [4.76178, 52.50184]]
68            ]
69          },
70          "openlr": "CwNisCVVaDPCAgBeAJIzEQ==",
71          "dataNotAvailable": false,
72          "arrivalPoints": [
73            {
74              "externalId": "ap-001",
75              "name": "AP North",
76              "projectedPoint": {
77                "type": "Point",
78                "coordinates": [4.761756449662269, 52.50180310447089]
79              }
80            }
81          ]
82        }
83      ],
84      "exits": [
85        {
86          "externalId": "exit-001",
87          "name": "Heiligeweg East Bound",
88          "roadName": "Heiligeweg",
89          "direction": "EAST",
90          "frc": 6,
91          "oneWayRoad": false,
92          "drivable": true,
93          "segmentedGeometry": {
94            "type": "MultiLineString",
95            "coordinates": [
96              [[4.76178, 52.50184], [4.76182, 52.50182], [4.76297, 52.50155]]
97            ]
98          },
99          "openlr": "CwNi3CVVrDPKAQB3/+MzGQ=="
100        }
101      ]
102    },
103    "elementsStatus": [
104      {
105        "externalId": "exit-001",
106        "type": "EXIT",
107        "status": "FAILED",
108        "error": {
109          "code": "ROUTING_LENGTH_MISMATCH",
110          "message": "Routed length deviates more than 30% from the expected length.",
111          "hint": "Verify that the params.length value matches the actual road distance."
112        }
113      },
114      {
115        "externalId": "approach-001",
116        "type": "APPROACH",
117        "status": "OK"
118      }
119    ]
120  },
121  "message": "Junction was not created because some elements have issues. To create the resource anyway, set the forceCreate flag to true."
122}

Response fields

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

modificationType (string) String that describes the modification type. Possible values: Created (junction was saved), NotCreated (junction was not saved due to element issues).

junction (object) The full junction definition (present when modificationType is Created).

  • id (string) Unique ID of the created junction.

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

  • name (string) The name of the junction.

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

    • name (string) The junction name as provided in the request.
    • externalId (string) The external identifier as provided in the request.
    • 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.
    • 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.
      • id (integer) The approach ID, unique in the junction context.
      • 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.
        • id (integer) The arrival point ID, unique in the approach context.
        • 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.
      • id (integer) The exit ID, unique in the junction context.
      • 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.

  • createdAt (string) ISO 8601 timestamp of when the junction was created.

  • lastModifiedAt (string) ISO 8601 timestamp of the last modification.

  • lastUserUpdatedAt (string) ISO 8601 timestamp of the last user-initiated update.

  • timeZone (string) The IANA time zone identifier for the junction location (e.g., "Europe/Amsterdam").

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
401Unauthorized
403Forbidden
400

Bad Request Example messages:

  • Junctions limit is reached. Remove some of your existing junctions or contact support.
  • At least 1 approach is required.
  • At least 1 exit is required.
  • Maximum number of approaches (20) exceeded.
  • Maximum number of exits (20) exceeded.
  • External ID exceeded maximum length of 250.
  • Maximum number of arrival points (3) per approach exceeded.
  • Geometry envelope area exceeds the maximum allowed size.
  • Maximum number of coordinates per leg exceeded.
422

Unprocessable Entity — The request is valid, but the junction was not saved because one or more approaches or exits have validation issues. The response body contains a dry-run preview of the junction with per-element status. To force creation, retry with forceCreate=true.

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": "At least 1 approach is required."
3}