Junction definition details

Request AccessRequest Access
Service version: v1
Last edit: 2022.08.19

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

https://api.tomtom.com/junction-analytics/junctions/1/{junctionId}/definition?key={Your_API_Key}&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 parameters

Description

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 parameters

Description

includeGeometry
boolean

If true, the junction geometry is included in the response.


Value: true or false

Request headers

Header

Value

Content-Type

application/json

If-Modified-Since

Optional, the date in the format of RFC 822, GMT.

If-None-Match

Optional, the ETag value from a previous response.

Example request

The following is an example curl request:

$ curl '/junction-analytics/junctions/1/{junctionId}/definition?key={Your_API_Key}&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.

Example response

The following JSON code block is an example response:

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          [19.44755981778522, 51.72758385424984],
13          [19.44698786140313, 51.72702850798893],
14          [19.447606192627404, 51.726214626143076],
15          [19.448688272269123, 51.72699499549654],
16          [19.44755981778522, 51.72758385424984]
17        ]
18      ]
19    }
20  },
21  "detectionConfig": {
22    "autodetectName": false
23  },
24  "junctionModel": {
25    "id": "19.4521-51.7766",
26    "name": "First Street - Second Street",
27    "countryCode": "DEU",
28    "driveOnLeft": false,
29    "trafficLights": true,
30    "approaches": [
31      {
32        "id": 1397964518,
33        "name": "First Street West Bound",
34        "roadName": "First Street",
35        "direction": "WEST",
36        "frc": 7,
37        "length": 192.77,
38        "oneWayRoad": false,
39        "excluded": false,
40        "drivable": true,
41        "segmentedGeometry": {
42          "type": "MultiLineString",
43          "coordinates": [
44            [
45              [19.45464, 51.77712],
46              [19.45452, 51.77711],
47              [19.45443, 51.77708]
48            ]
49          ]
50        },
51        "userPoints": [
52          {
53            "type": "Point",
54            "coordinates": [19.45464, 51.77712]
55          },
56          {
57            "type": "Point",
58            "coordinates": [19.45443, 51.77708]
59          }
60        ],
61        "openlr": "Cw3VGCTJOhJTB/5H/toWSXY=",
62        "dataNotAvailable": false
63      },
64      {
65        "id": -2036692957,
66        "name": "Second Street North Bound",
67        "roadName": "Second Street",
68        "direction": "NORTH",
69        "frc": 4,
70        "length": 236.16,
71        "oneWayRoad": true,
72        "excluded": false,
73        "drivable": true,
74        "segmentedGeometry": {
75          "type": "MultiLineString",
76          "coordinates": [
77            [
78              [19.45265, 51.77446],
79              [19.45224, 51.77653],
80              [19.45224, 51.77657]
81            ]
82          ]
83        },
84        "userPoints": [
85          {
86            "type": "Point",
87            "coordinates": [19.45265, 51.77446]
88          },
89          {
90            "type": "Point",
91            "coordinates": [19.45224, 51.77657]
92          }
93        ],
94        "openlr": "Cw3VGCTJOhJTB/5H/toWSXY=",
95        "dataNotAvailable": false
96      }
97    ],
98    "exits": [
99      {
100        "id": 2032081462,
101        "name": "First Street North Bound",
102        "roadName": "First Street",
103        "direction": "NORTH",
104        "frc": 4,
105        "oneWayRoad": false,
106        "drivable": true,
107        "segmentedGeometry": {
108          "type": "MultiLineString",
109          "coordinates": [
110            [
111              [19.45224, 51.77657],
112              [19.45222, 51.77665]
113            ]
114          ]
115        },
116        "openlr": "Dw3VGCTJOhJTB/5H/toWSXY="
117      },
118      {
119        "id": -351401112,
120        "name": "Second Street East Bound",
121        "roadName": "Second Street",
122        "direction": "EAST",
123        "frc": 7,
124        "oneWayRoad": false,
125        "drivable": true,
126        "segmentedGeometry": {
127          "type": "MultiLineString",
128          "coordinates": [
129            [
130              [19.45224, 51.77657],
131              [19.4525, 51.77659]
132            ]
133          ]
134        },
135        "openlr": "Ew3VGCTJOhJTB/5H/toWSXY="
136      }
137    ]
138  }
139}

Response fields

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

Field

Description

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 following this table.

statusDetail
string

This appears in the case of an ERRORstatus, 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.
detectionConfig.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. Not available in ERROR status.

junctionModel.name
string

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

junctionModel.countryCode
string

The three-letter country code defined in the

ISO 3166-1 alpha-3 standard

.

junctionModel.driveOnLeft
boolean

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

junctionModel.trafficLights
boolean

This is true if traffic lights are inside the creation area.

junctionModel.approaches[]
array		Contains junction approaches. Min number of approaches: 1
junctionModel.approaches[].id
integer		The approach ID is unique in the junction context.
junctionModel.approaches[].name
string

Created based on the name and road direction.


Example: "Some Street West Bound".

junctionModel.approaches[].roadName
string		If the road has no name, it will be "Unnamed road".
junctionModel.approaches[].direction
string

One of the values: SOUTH, WEST, EAST, NORTH, CLOCKWISE, COUNTER_CLOCKWISE.

junctionModel.approaches[].frc
integer

Functional Road Class. One of the values: 0, 1 , 2, 3, 4, 5, 6, 7.

junctionModel.approaches[].length
float		Length of the given approach in meters.
junctionModel.approaches[].oneWayRoad
boolean

It is true if it is a one-direction road or not a single carriageway road.

junctionModel.approaches[].excluded
boolean		Indicates that live data for the approach is collected.
junctionModel.approaches[].drivable
boolean		Indicates if the road is drivable.
junctionModel.approaches[].segmentedGeometry
object

Geometry of the given approach, split by map segments. See the

GeoJson MultiLineString specification

.

junctionModel.approaches[].userPoints
array

Array of user-defined points that the geometry routes through. See the

GeoJson Point specification

.

junctionModel.approaches[].openlr
string

Geometry of given approach, encoded into OpenLR format. See the OpenLR specification.

junctionModel.exits[]
array

Contains junction exits.


Min numbers of exits: 1.

junctionModel.exits[].id
integer		The exit ID is unique in the junction context.
junctionModel.exits[].name
string

This is created based on the name and road direction.


Example: "Typical Street West Bound".

junctionModel.exits[].roadName
string		If the road has no name, it will be "Unnamed road".
junctionModel.exits[].direction
string

One of the values: SOUTH, WEST, EAST, NORTH, CLOCKWISE, COUNTER_CLOCKWISE.

junctionModel.exits[].frc
integer

Functional Road Class. One of the values: 0, 1 , 2, 3, 4, 5, 6, 7.

junctionModel.exits[].oneWayRoad
boolean

It is true if it is a one-direction road or not a single carriageway road.

junctionModel.exits[].drivable
boolean		Indicates ifthe road is drivable.
junctionModel.exits[].segmentedGeometry
object

Geometry of the given exit, split by map segments. See the

GeoJson MultiLineString specification

.

junctionModel.exits[].openlr
string

Geometry of the given exit, encoded into OpenLR format. See the OpenLR specification

Junction status

The following table shows the junction status.

Value

Description

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

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

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

Field

Description

errorMessage
string		The problem description.

Example error response

The following is an example error response:

1{
2  "errorMessage": "Junction of id 5fd8da2b84510126b9d18b0d not found"
3}