Developer

Junction definition list

Request Access
Service version: v1
Last edit: 2024.04.09

Important note This Junction Analytics API is unavailable on a Freemium or Pay As You Grow (PAYG) basis. Click Request Access to contact our Sales team.

Purpose

Junction definition details is a REST API endpoint that reads static information about about a paginated list of junctions. For all of these junctions, it contains the junction ID, name, status, and other static details.

The response can also, on demand, contain information about the junction model's 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.

Additionally, the endpoint supports the If-Modified-Since HTTP header. When this header is set in the request, the API will return only the junctions that were modified after the specified date. This enables efficient retrieval of recently updated junctions without requiring the entire dataset to be fetched.

Request data

You can obtain the junction definition list by sending a GET request.

  • 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/definition?key={Your_API_Key}&page={page}&size={size}&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.
ParameterDescription

key
string

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

page
integer

Default value: 0

size
integer

Max: 1000

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.

Example request

The following is an example curl request:

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

Response data

This response returns the junction definition list.

Example response

The following is an example response in JSON format:

Response body - JSON
1{
2  "content": [
3    {
4      "id": "5fd9bb5a88a13608d7b5d92d",
5      "name": "First Street - Second Street",
6      "status": "ACTIVE",
7      "rawJunction": {
8        "type": "Feature",
9        "properties": {},
10        "geometry": {
11          "type": "Polygon",
12          "coordinates": [
13            [
14              [19.44755981778522, 51.72758385424984],
15              [19.44698786140313, 51.72702850798893],
16              [19.447606192627404, 51.726214626143076],
17              [19.448688272269123, 51.72699499549654],
18              [19.44755981778522, 51.72758385424984]
19            ]
20          ]
21        }
22      },
23      "detectionConfig": {
24        "autodetectName": false
25      },
26      "junctionModel": {
27        "name": "First Street - Second Street",
28        "countryCode": "DEU",
29        "driveOnLeft": false,
30        "trafficLights": true,
31        "approaches": [
32          {
33            "id": 1397964518,
34            "name": "First Street West Bound",
35            "roadName": "First Street",
36            "direction": "WEST",
37            "frc": 7,
38            "length": 192.77,
39            "oneWayRoad": false,
40            "excluded": false,
41            "drivable": true,
42            "segmentedGeometry": {
43              "type": "MultiLineString",
44              "coordinates": [
45                [
46                  [19.45464, 51.77712],
47                  [19.45452, 51.77711],
48                  [19.45443, 51.77708]
49                ]
50              ]
51            },
52            "userPoints": [
53              {
54                "type": "Point",
55                "coordinates": [19.45464, 51.77712]
56              },
57              {
58                "type": "Point",
59                "coordinates": [19.45443, 51.77708]
60              }
61            ],
62            "openlr": "Cw3VGCTJOhJTB/5H/toWSXY=",
63            "dataNotAvailable": false
64          },
65          {
66            "id": -2036692957,
67            "name": "Second Street North Bound",
68            "roadName": "Second Street",
69            "direction": "NORTH",
70            "frc": 4,
71            "length": 236.16,
72            "oneWayRoad": true,
73            "excluded": false,
74            "drivable": true,
75            "segmentedGeometry": {
76              "type": "MultiLineString",
77              "coordinates": [
78                [
79                  [19.45265, 51.77446],
80                  [19.45224, 51.77653],
81                  [19.45224, 51.77657]
82                ]
83              ]
84            },
85            "userPoints": [
86              {
87                "type": "Point",
88                "coordinates": [19.45265, 51.77446]
89              },
90              {
91                "type": "Point",
92                "coordinates": [19.45224, 51.77657]
93              }
94            ],
95            "openlr": "Cw3VGCTJOhJTB/5H/toWSXY=",
96            "dataNotAvailable": false
97          }
98        ],
99        "exits": [
100          {
101            "id": 2032081462,
102            "name": "First Street North Bound",
103            "roadName": "First Street",
104            "direction": "NORTH",
105            "frc": 4,
106            "oneWayRoad": false,
107            "drivable": true,
108            "segmentedGeometry": {
109              "type": "MultiLineString",
110              "coordinates": [
111                [
112                  [19.45224, 51.77657],
113                  [19.45222, 51.77665]
114                ]
115              ]
116            },
117            "openlr": "Dw3VGCTJOhJTB/5H/toWSXY="
118          },
119          {
120            "id": -351401112,
121            "name": "Second Street East Bound",
122            "roadName": "Second Street",
123            "direction": "EAST",
124            "frc": 7,
125            "oneWayRoad": false,
126            "drivable": true,
127            "segmentedGeometry": {
128              "type": "MultiLineString",
129              "coordinates": [
130                [
131                  [19.45224, 51.77657],
132                  [19.4525, 51.77659]
133                ]
134              ]
135            },
136            "openlr": "Ew3VGCTJOhJTB/5H/toWSXY="
137          }
138        ]
139      },
140      "createdAt": "2024-12-12T10:23:39.386Z",
141      "lastModifiedAt": "2024-12-12T10:25:49.843Z",
142      "lastUserUpdatedAt": "2024-12-12T10:23:39.386Z",
143      "timeZone": "Europe/Berlin"
144    },
145    {
146      "id": "675ab9abee76bd332ab14asf",
147      "name": "Downing Street - Third Street",
148      "status": "ACTIVE",
149      "rawJunction": {
150        "type": "Feature",
151        "properties": {
152            "radius": 11.913586321398501
153        },
154        "geometry": {
155          "type": "Point",
156          "coordinates": [
157              19.386745414555577,
158              51.65369585379912
159          ]
160        }
161      },
162      "detectionConfig": {
163        "autodetectName": false
164      },
165      "junctionModel": {
166        "name": "First Street - Second Street",
167        "countryCode": "POL",
168        "driveOnLeft": false,
169        "trafficLights": true,
170        "approaches": [
171          {
172            "id": -293007300,
173            "name": "20th January North Bound",
174            "roadName": "20th January",
175            "direction": "NORTH",
176            "frc": 7,
177            "length": 164.55,
178            "oneWayRoad": false,
179            "excluded": false,
180            "drivable": true,
181            "segmentedGeometry": {
182              "type": "MultiLineString",
183              "coordinates": [
184                [
185                  [19.38643, 51.65321],
186                  [19.38675, 51.65369]
187                ]
188              ]
189            },
190            "userPoints": [
191              {
192                "type": "Point",
193                "coordinates": [19.3878, 51.65291]
194              },
195              {
196                "type": "Point",
197                "coordinates": [19.38675, 51.65369]
198              }
199            ],
200            "openlr": "Cw3JcSS7IST2Av+XAE47EQ==",
201            "dataNotAvailable": false
202          },
203          {
204            "id": -61205119,,
205            "name": "Third Street North Bound",
206            "roadName": "Third Street",
207            "direction": "NORTH",
208            "frc": 7,
209            "length": 193.22,
210            "oneWayRoad": true,
211            "excluded": false,
212            "drivable": true,
213            "segmentedGeometry": {
214              "type": "MultiLineString",
215              "coordinates": [
216                [
217                  [19.38611, 51.65509],
218                  [19.38601, 51.65437]
219                ]
220              ]
221            },
222            "userPoints": [
223              {
224                "type": "Point",
225                "coordinates": [19.38611, 51.65509]
226              },
227              {
228                "type": "Point",
229                "coordinates": [19.38675, 51.65369]
230              }
231            ],
232            "openlr": "Cw3JIyS7hjvwAwBA/3Q7Gg==",
233            "dataNotAvailable": false
234          }
235        ],
236        "exits": [
237          {
238            "id": -22856910,
239            "name": "Third Street North Bound",
240            "roadName": "Third Street",
241            "direction": "NORTH",
242            "frc": 7,
243            "oneWayRoad": true,
244            "drivable": true,
245            "segmentedGeometry": {
246              "type": "MultiLineString",
247              "coordinates": [
248                [
249                  [19.38675, 51.65369],
250                  [19.38735, 51.65369]
251                ]
252              ]
253            },
254            "openlr": "Cw3JQSS7RTvoAwCOAII7MMo="
255          }
256        ]
257      },
258      "createdAt": "2024-12-12T10:23:39.386Z",
259      "lastModifiedAt": "2024-12-12T10:25:49.843Z",
260      "lastUserUpdatedAt": "2024-12-12T10:23:39.386Z",
261      "timeZone": "Europe/Warsaw"
262    }
263  ],
264  "pageable": {
265    "pageNumber": 0,
266    "pageSize": 3,
267    "offset": 0,
268    "paged": true,
269    "unpaged": false
270  },
271  "last": false,
272  "totalElements": 127,
273  "totalPages": 43,
274  "numberOfElements": 2,
275  "first": true,
276  "size": 3,
277  "number": 0,
278  "empty": false
279}

Response fields

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

content[] (array) This is a list of junctions definitions.

  • id (string) Unique ID of the junction.
  • name (string) The name of the junction as generated automatically, or provided in the junction definition creation request.
  • status (string) One of the values: PREVIEW, ACTIVE, PENDING_UPDATE, ERROR. More details are available in the following section.
  • statusDetail (string) This appears in the case of an ERROR status, and provides further explanation.
  • rawJunction (object) A GeoJSON Feature, Polygon, or Point (with the radius property). It contains the junction boundary used in the creation process.
  • detectionConfig (object) Contains the detection configuration used in junction creation.
    • autodetectName (boolean) If true, the junction name was created based on its approaches.
  • junctionModel (object) This contains junction geometry and other data. It is not available when the includeGeometry query param is false, and is not available in ERROR status.
    • name (string) The name of the junction as automatically generated, 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 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: GeoJSON MultiLineString specification.
      • userPoints (array) Array of user-defined points that the geometry routes through. See: GeoJSON Point specification.
      • openlr (string) Geometry of given approach, encoded into OpenLR format. See the OpenLR specification.
      • dataNotAvailable (boolean) Indicates whether live data is available for the approach.
    • 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.
      • openlr (string) Geometry of the given exit, encoded into OpenLR format. See the OpenLR specification.
  • createdAt (date) The timestamp indicating when the junction definition was initially created, in ISO 8601 format.
  • lastModifiedAt (date) The timestamp of the most recent update to the junction definition, in ISO 8601 format.
  • lastUserUpdatedAt (date) The timestamp of the last update made by a user to the junction definition, in ISO 8601 format.
  • timeZone (string) The time zone associated with the junction, represented in the IANA time zone format (e.g., Europe/Warsaw). pageable (object) This contains information about the content page.
  • pageNumber (integer) This is the number of the current page.
  • pageSize (integer) This is the size of the current page.
  • offset (integer) This is the offset of data.
  • paged (boolean) This is if content is paged.
  • unpaged (boolean) This is if content is unpaged.

last (boolean) This is if the current page is the last page.

totalElements (integer) This is the total number of elements.

totalPages (integer) This is the number of total pages.

numberOfElements (integer) This is the number of elements currently on this page.

first (boolean) This is if the current page is the first one.

size (integer) This is the size of the page.

number (integer) This is the number of the current page.

empty (boolean) This is if the current page is empty.

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).

Response errors

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

Error response codes

The following table contains the error response codes.

CodeDescription
401

Unauthorized

403

Forbidden

Error response fields

FieldDescription

errorMessage
string

Problem description.

Example error response

Response error - JSON
1{
2  "errorMessage": "Maximum page size exceeded, maximum page size is 1000."
3}