Sorry, you need to enable JavaScript to visit this website.

Junction definition details

Junction definition details

Junction definition details is a REST API endpoint to read 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, its approaches and exits. It does not include any dynamic real-time data that is available using Junction live data details and Junction live data list endpoints.

You can obtain the Junction definition details by sending a GET request, as shown in the following example:

GET https://api.tomtom.com/junction-analytics/junctions/1/<junctionId>/definition?key=<apiKey>&includeGeometry=<includeGeometry>

Path parameter

The following table shows the path parameter:

ParameterTypeOptionalDefaultDescription

junctionId

String

false

n/a

n/a

Query parameters

The following table shows the query parameters:

ParameterTypeOptionalDefaultDescription

key

String

false

n/a

n/a

includeGeometry

Boolean

true

false

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

Headers

HeaderValue

Content-Type

application/json

If-Modified-Since

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

If-None-Match

Optional ETag value from previous response.

Example request

The following is an example request:

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

Response

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

Response fields

FieldTypeOptionalDescription

id

String

false

Unique ID of the junction.

name

String

false

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

status

String

false

One of the values: PREVIEW, ACTIVE, PENDING_UPDATE, ERROR. More details following this table.

statusDetail

String

true

This appears in the case of an ERROR status, and provides further explanation.

detectionConfig

Object

false

Contains the detection configuration used in junction creation.

detectionConfig.autodetectName

Boolean

false

If true, the junction name was created based on its approaches.

junctionModel

Object

true

This contains junction geometry and other data.

It is not available when includeGeometry query param is false.

Not available in ERROR status.

junctionModel.id

String

false

This is based on the junction center point.

junctionModel.name

String

false

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

junctionModel.countryCode

String

false

The three-letter country code defined in ISO 3166-1 alpha-3 standard

junctionModel.driveOnLeft

Boolean

false

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

junctionModel.trafficLight

Boolean

false

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

junctionModel.approaches[]

Array

false

Contains junction approaches.
Min number of approaches: 1

junctionModel.approaches[].id

Int

false

The approach ID is unique in the junction context.

junctionModel.approaches[].name

String

false

Created based on the name and road direction.
Example: "Some Street West Bound".

junctionModel.approaches[].roadName

String

false

If the road has no name, it will be "Unnamed road".

junctionModel.approaches[].direction

String

false

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

junctionModel.approaches[].frc

Int

false

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

junctionModel.approaches[].oneWayRoad

Boolean

false

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

junctionModel.approaches[].segmentedGeometry

GeoJson Feature, MultiLineString

false

Geometry of given approach, split by map segments. GeoJson MultiLineString specification

junctionModel.exits[]

Array

false

Contains junction exits.
Min numbers of exits: 1

junctionModel.exits[].name

String

false

This is created based on the name and road direction.
Example: "Typical Street West Bound".

junctionModel.exits[].roadName

String

false

If the road has no name, it will be "Unnamed road".

junctionModel.exits[].direction

String

false

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

junctionModel.exits[].frc

Int

false

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

junctionModel.exits[].oneWayRoad

Boolean

false

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

junctionModel.exits[].segmentedGeometry

GeoJson Feature, MultiLineString

false

Geometry of given exit, split by map segments. GeoJson MultiLineString specification

Junction status

The following table shows the junction status:

ValueDescription

PREVIEW

Junction is processing, live data is not served.

ACTIVE

Junction is processed, live data is served.

PENDING_UPDATE

Junction is processing after update, live data is not served.

ERROR

Something bad happened (an error occurred).

Example response

The following is an example response:

HTTP/1.1 200 OK
{
    "id": "5fd9bb5a88a13608d7b5d92d",
    "name": "First Street - Second Street",
    "status": "ACTIVE",
    "detectionConfig": {
        "autodetectName": false
    },
    "junctionModel": {
        "id": "19.4521-51.7766",
        "name": "First Street - Second Street",
        "countryCode": "DEU",
        "driveOnLeft": false,
        "trafficLight": true,
        "approaches": [
            {
                "id": 1397964518,
                "name": "First Street West Bound",
                "roadName": "First Street",
                "direction": "WEST",
                "frc": 7,
                "length": 192.77000427246094,
                "oneWayRoad": false,
                "excluded": false,
                "segmentedGeometry": {
                  "type": "MultiLineString",
                  "coordinates": [
                    [
                        [
                            19.45464,
                            51.77712
                        ],
                        [
                            19.45452,
                            51.77711
                        ],
                        [
                            19.45443,
                            51.77708
                        ]
                     ]
                  ]
                }
            },
            {
                "id": -2036692957,
                "name": "Second Street North Bound",
                "roadName": "Second Street",
                "direction": "NORTH",
                "frc": 4,
                "length": 236.16000366210938,
                "oneWayRoad": true,
                "excluded": false,
                "segmentedGeometry": {
                  "type": "MultiLineString",
                  "coordinates": [
                    [
                        [
                            19.45265,
                            51.77446
                        ],
                        [
                            19.45224,
                            51.77653
                        ],
                        [
                            19.45224,
                            51.77657
                        ]
                     ]
                  ]
                }
            }
        ],
        "exits": [
            {
                "name": "First Street North Bound",
                "roadName": "First Street",
                "direction": "NORTH",
                "frc": 4,
                "oneWayRoad": false,
                "segmentedGeometry": {
                  "type": "MultiLineString",
                  "coordinates": [
                    [
                        [
                            19.45224,
                            51.77657
                        ],
                        [
                            19.45222,
                            51.77665
                        ]
                     ]
                  ]
                }
            },
            {
                "name": "Second Street East Bound",
                "roadName": "Second Street",
                "direction": "EAST",
                "frc": 7,
                "oneWayRoad": false,
                "segmentedGeometry": {
                  "type": "MultiLineString",
                  "coordinates": [
                    [
                        [
                            19.45224,
                            51.77657
                        ],
                        [
                            19.4525,
                            51.77659
                        ]
                     ]
                  ]
                }
            }
        ]
    }
}

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:

CodeNameDescriptionExample error message

401

Unauthorized

n/a

n/a

403

Forbidden

n/a

n/a

404

Not Found

Junction with the specified id does not exist or is in ARCHIVED state

Junction of id 5fd8da2b84510126b9d18b0d is not found.

Error response field

FieldTypeOptionalDescription

errorMessage

String

true

The problem description.

Example error response

The following is an example error response:

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