Junction definition details

Request Access
Service version: v1
Last edit: 2022.08.05

Purpose

Junction definition details is a REST API endpoint that reads static information about a selected junction. It contains the junction ID, name, status, and other static details of a selected junction.

The response can also, on demand, contain information about the junction model: junction boundary and its approaches and exits. It does not include any dynamic real-time data that is available using the Junction live data details and Junction live data list endpoints.

Request data

You can obtain the Junction definition details by sending a GET 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 parameters tables for their values. The generic request format is as follows.

HTTPS method: GET

GET
URL request example
https://api.tomtom.com/junction-analytics/junctions/1/{junctionId}/definition?key={apiKey}&includeGeometry={includeGeometry}

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
junctionId
string		The unique junction id that must be used in the request path.
key
string		An API Key valid for the requested service.
Value: Your valid API Key.
Optional parametersDescription
includeGeometry
boolean		If true, the junction geometry is included in the response.
Value: true or false

Request headers

HeaderValue
Content-Typeapplication/json
If-Modified-SinceOptional, the date in the format of RFC 822, GMT.
If-None-MatchOptional, the ETag value from a previous response.

Example request

The following is an example curl request:

GET
curl command example
$ curl '/junction-analytics/junctions/1/{junctionId}/definition?key={apiKey}&includeGeometry={includeGeometry}' -i -X GET \
    -H 'Content-Type: application/json' \

Response data

This response returns junction definition details. The following table describes all of the fields that can appear in a response.

Response fields

FieldDescription
idUnique ID of the junction.
nameThe name of the junction as generated automatically, or provided in the junction definition creation request.
statusOne of the values: PREVIEW, ACTIVE, PENDING_UPDATE, ERROR. More details are available following this table.
statusDetailThis appears in the case of an ERRORstatus, and provides further explanation.
rawJunctionA GeoJson Feature, Polygon or Point (with the radius property).
It contains the junction boundary used in the creation process.
detectionConfig{}Contains the detection configuration used in junction creation.
detectionConfig.autodetectNameIf true, the junction name was created based on its approaches.
junctionModel{}This contains junction geometry and other data. It is not available when the includeGeometry query param is false. Not available in ERROR status.
junctionModel.nameThe name of the junction as generated automatically, or provided in the junction definition creation request.
junctionModel.countryCodeThe three-letter country code defined in the ISO 3166-1 alpha-3 standard.
junctionModel.driveOnLeftThis is a flag with information about left-hand traffic (LHT) or right-hand traffic (RHT).
junctionModel.trafficLightsThis is true if traffic lights are inside the creation area.
junctionModel.approaches[]Contains junction approaches. Min number of approaches: 1
junctionModel.approaches[].idThe approach ID is unique in the junction context.
junctionModel.approaches[].nameCreated based on the name and road direction.
Example: "Some Street West Bound".
junctionModel.approaches[].roadNameIf the road has no name, it will be "Unnamed road".
junctionModel.approaches[].directionOne of the values: SOUTH, WEST, EAST, NORTH, CLOCKWISE, COUNTER_CLOCKWISE.
junctionModel.approaches[].frcFunctional Road Class. One of the values: 0, 1, 2, 3, 4, 5, 6, 7.
junctionModel.approaches[].lengthLength of the given approach in meters.
junctionModel.approaches[].oneWayRoadIt is true if it is a one-direction road or not a single carriageway road.
junctionModel.approaches[].excludedIndicates that live data for the approach is collected.
junctionModel.approaches[].drivableIndicates if the road is drivable.
junctionModel.approaches[].segmentedGeometryGeometry of the given approach, split by map segments. See the GeoJson MultiLineString specification.
junctionModel.approaches[].userPointsArray of user-defined points that the geometry routes through. See the GeoJson Point specification.
junctionModel.approaches[].openlrGeometry of given approach, encoded into OpenLR format. See the OpenLR specification.
junctionModel.exits[]Contains junction exits.
Min numbers of exits: 1.
junctionModel.exits[].idThe exit ID is unique in the junction context.
junctionModel.exits[].nameThis is created based on the name and road direction.
Example: "Typical Street West Bound".
junctionModel.exits[].roadNameIf the road has no name, it will be "Unnamed road".
junctionModel.exits[].directionOne of the values: SOUTH, WEST, EAST, NORTH, CLOCKWISE, COUNTER_CLOCKWISE.
junctionModel.exits[].frcFunctional Road Class. One of the values: 0, 1, 2, 3, 4, 5, 6, 7.
junctionModel.exits[].oneWayRoadIt is true if it is a one-direction road or not a single carriageway road.
junctionModel.exits[].drivableIndicates ifthe road is drivable.
junctionModel.exits[].segmentedGeometryGeometry of the given exit, split by map segments. See the GeoJson MultiLineString specification.
junctionModel.exits[].openlrGeometry of the given exit, encoded into OpenLR format. See the OpenLR specification

Junction status

The following table shows the junction status:

ValueDescription
PREVIEWJunction is processing, live data is not served.
ACTIVEJunction is processed, live data is served.
PENDING_UPDATEJunction is processing after update, live data is not served.
ERRORSomething bad happened (an error occurred).

Example response

The following JSON code block is an example response:

Response body - JSON
1{
2    "id": "5fd9bb5a88a13608d7b5d92d",
3    "name": "First Street - Second Street",
4    "status": "ACTIVE",
5    "rawJunction": {
6        "type": "Feature",
7        "properties": {},
8        "geometry": {
9        "type": "Polygon",
10        "coordinates": [
11            [
12                [
13                    19.44755981778522,
14                    51.72758385424984
15                ],
16                [
17                    19.44698786140313,
18                    51.72702850798893
19                ],
20                [
21                    19.447606192627404,
22                    51.726214626143076
23                ],
24                [
25                    19.448688272269123,
26                    51.72699499549654
27                ],
28                [
29                    19.44755981778522,
30                    51.72758385424984
31                ]
32            ]
33          ]
34        }
35    },
36    "detectionConfig": {
37        "autodetectName": false
38    },
39    "junctionModel": {
40        "id": "19.4521-51.7766",
41        "name": "First Street - Second Street",
42        "countryCode": "DEU",
43        "driveOnLeft": false,
44        "trafficLights": true,
45        "approaches": [
46            {
47                "id": 1397964518,
48                "name": "First Street West Bound",
49                "roadName": "First Street",
50                "direction": "WEST",
51                "frc": 7,
52                "length": 192.77,
53                "oneWayRoad": false,
54                "excluded": false,
55                "drivable": true,
56                "segmentedGeometry": {
57                  "type": "MultiLineString",
58                  "coordinates": [
59                    [
60                        [
61                            19.45464,
62                            51.77712
63                        ],
64                        [
65                            19.45452,
66                            51.77711
67                        ],
68                        [
69                            19.45443,
70                            51.77708
71                        ]
72                     ]
73                  ]
74                },
75                "userPoints": [
76                  {
77                    "type": "Point",
78                    "coordinates": [
79                        19.45464,
80                        51.77712
81                    ]
82                  },
83                  {
84                    "type": "Point",
85                    "coordinates": [
86                        19.45443,
87                        51.77708
88                    ]
89                  }
90                ],
91                "openlr": "Cw3VGCTJOhJTB/5H/toWSXY=",
92                "dataNotAvailable": false
93            },
94            {
95                "id": -2036692957,
96                "name": "Second Street North Bound",
97                "roadName": "Second Street",
98                "direction": "NORTH",
99                "frc": 4,
100                "length": 236.16,
101                "oneWayRoad": true,
102                "excluded": false,
103                "drivable": true,
104                "segmentedGeometry": {
105                  "type": "MultiLineString",
106                  "coordinates": [
107                    [
108                        [
109                            19.45265,
110                            51.77446
111                        ],
112                        [
113                            19.45224,
114                            51.77653
115                        ],
116                        [
117                            19.45224,
118                            51.77657
119                        ]
120                     ]
121                  ]
122                },
123                "userPoints": [
124                  {
125                    "type": "Point",
126                    "coordinates": [
127                        19.45265,
128                        51.77446
129                    ]
130                  },
131                  {
132                    "type": "Point",
133                    "coordinates": [
134                        19.45224,
135                        51.77657
136                    ]
137                  }
138                ],
139                "openlr": "Cw3VGCTJOhJTB/5H/toWSXY=",
140                "dataNotAvailable": false
141            }
142        ],
143        "exits": [
144            {
145                "id": 2032081462,
146                "name": "First Street North Bound",
147                "roadName": "First Street",
148                "direction": "NORTH",
149                "frc": 4,
150                "oneWayRoad": false,
151                "drivable": true,
152                "segmentedGeometry": {
153                  "type": "MultiLineString",
154                  "coordinates": [
155                    [
156                        [
157                            19.45224,
158                            51.77657
159                        ],
160                        [
161                            19.45222,
162                            51.77665
163                        ]
164                     ]
165                  ]
166                },
167                "openlr": "Dw3VGCTJOhJTB/5H/toWSXY="
168            },
169            {
170                "id": -351401112,
171                "name": "Second Street East Bound",
172                "roadName": "Second Street",
173                "direction": "EAST",
174                "frc": 7,
175                "oneWayRoad": false,
176                "drivable": true,
177                "segmentedGeometry": {
178                  "type": "MultiLineString",
179                  "coordinates": [
180                    [
181                        [
182                            19.45224,
183                            51.77657
184                        ],
185                        [
186                            19.4525,
187                            51.77659
188                        ]
189                     ]
190                  ]
191                },
192                "openlr": "Ew3VGCTJOhJTB/5H/toWSXY="
193            }
194        ]
195    }
196}

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.

HTTP error response codes

The following table shows the error response codes:

CodeDescription
401Unauthorized
403Forbidden
404Not Found
  • Junction with the specified id does not exist or is in ARCHIVED state.
  • Junction of id 5fd8da2b84510126b9d18b0d is not found.

Error response field

FieldDescription
errorMessageThe problem description.

Example error response

The following is an example error response:

Response error - JSON
1{
2    "errorMessage": "Junction of id 5fd8da2b84510126b9d18b0d not found"
3}