INRIX IQ logo

REFERENCE

Speed Buckets

Speed buckets are used to determine what color is displayed on a road depending on what value the speed has as a percentage of the reference speed. You can use the default speed buckets, or you can create your own speed buckets which you specify by using the SpeedBucketId parameter. Each speed bucket contains information on the minimum and maximum percentage of reference speed in order for a speed to be contained in that bucket, as well as information for how that speed bucket is drawn, such as color, style, and width.


Description: Standard CRUD (Create, Retrieve, Update, and Delete) calls are provided for creating and managing your speed buckets. Speed buckets define how colored lines are painted on TrafficTiles based on speed, congestion level or/and FRCs.

/?Action=CreateSpeedBucket

GET Generates a new speed bucket and returns a unique SpeedBucketID value.

Parameters

  = required
Name Located In Type Description
action Query String Use CreateSpeedBucket
Token Query String A valid authorization token returned in response to a GetSecurityToken request.
Name Query String The name of the speed bucket.
Description Query String A textual description of the speed bucket.
Private Query Boolean Specifies whether the bucket is accessible by all vendors in the group, or only the defining vendor. The default is false.
Value Description
true The bucket cannot be viewed or used by any other vendor in the group.
false (default) The bucket can be viewed and used by other vendors in the same vendor group. It cannot be viewed or used by any vendors in another vendor group.
SpeedBucketXML Query String An XML definition of INRIX speed bucket. Only the type attribute is specified; the other attributes are generated when the speed bucket is created.
Value Type Description
type Attribute (integer) The type of speed bucket. When calling CreateSpeedBucket, specify ONLY this attribute, as shown in the example below.
Value Description
1 Congestion: Current speed as a percentage of the free flow or reference speed. For example, the four buckets defined in the INRIX speed bucket ID 1 are represented as:
  1. Color = black if speed is 0-31% of free flow speed.
  2. Color = red if speed is 32-62% of free flow speed.
  3. Color = yellow if speed is 63-92% of free flow speed.
  4. Color = forestgreen if speed is 93-100% of free flow speed.
2 Speed: The absolute current reported speeds in mph or kph. For example, you might have a bucket defined as:
  1. Color = black if speed is 0-15 MPH.
  2. Color = red if speed is 16-30 MPH.
  3. Color = yellow if speed is 31-40 MPH.
  4. Color = green if speed is 41+.
3 Relative Congestion: The percentage difference between the current congestion (current speed versus free flow speed) and the typical congestion for the current time of day and day of week (typical speed versus free flow speed).
4 Relative Speed: The absolute difference between the current reported speed (mph or kph) and the typical speed for the current time of day and day of week.
RoadClosure Element Information for how a road closure is displayed. Note that pen colors can be either .NET Color Names or ARGB color values in standard web format (e.g., '#00112233').
Name Type Description
penStyle Attribute (integer) The style of the pen used to draw the section of road. 1 for solid; 2 for hatched.
backColor Attribute (string) The color for solid pens, and the background color for hatched pens. See Notes below for format.
foreColor Attribute (string) The accent color for hatched pens. See Notes below for format.
hatchStyle Attribute (string) The style of hatched pens. See .NET hatch styles for values.
penWidthPercent Attribute (integer) The percentage of the pen width used for drawing the road.
Buckets Element A collection of buckets that defines how groups of speeds are displayed. Note that pen colors can be either .NET Color Names or ARGB color values in standard web format (e.g., '#00112233').
Name Type Description
Bucket Element Data on how a range of speed data is displayed.
Name Type Description
num Attribute (integer) The index of the bucket in the series of bucket elements.
min Attribute (integer) The minimum value for data that goes into this bucket.
max Attribute (integer) The maximum value for data that goes into this bucket.
penStyle Attribute (integer) The style of the pen used to draw the section of road. 1 for solid; 2 for hatched.
backColor Attribute (string) The color for solid pens, and the background color for hatched pens. See Notes below for format.
foreColor Attribute (string) The accent color for hatched pens. See Notes below for format.
hatchStyle Attribute (string) The style of hatched pens. See .NET hatch styles for values.
penWidthPercent Attribute (integer) The percentage of the pen width used for drawing the road.

Notes

Speed buckets are ranges of speeds or percentages used to qualify TMC data, providing a high level view of congestion or speed. Previously these buckets were predetermined by INRIX. You can use the speed bucket API to set your own ranges or “buckets” for use with the TMC speed APIs and the tile server. There are four types of speed buckets that you can create, as shown below, with their type values:

  1. Congestion: Current speed as a percentage of the free flow or reference speed. For example, the four buckets defined in the INRIX speed bucket ID 1 are represented as:
    1. Color = black if speed is 0-31% of free flow speed.
    3. Color = red if speed is 32-62% of free flow speed.
    4. Color = yellow if speed is 63-92% of free flow speed.
    5. Color = forestgreen if speed is 93-100% of free flow speed.
  2. Speed: The absolute current reported speeds in mph or kph. For example, you might have a bucket defined as:
    1. Color = black if speed is 0-15 MPH.
    2. Color = red if speed is 16-30 MPH.
    3. Color = yellow if speed is 31-40 MPH.
    4. Color = green if speed is 41+.
  3. Relative Congestion: The percentage difference between the current congestion (current speed versus free flow speed) and the typical congestion for the current time of day and day of week (typical speed versus free flow speed).
  4. Relative Speed: The absolute difference between the current reported speed (mph or kph) and the typical speed for the current time of day and day of week.

All vendors have access to the six pre-defined INRIX speed buckets. These speed buckets are represented by SpeedBucketIDs 1-6. You can retrieve definitions of each of these speed buckets by calling GetSpeedBucket with SpeedBucketID set to one of these six values. Call GetSpeedBucket with no speedbucketID to list all the available values.

When creating a speed bucket using CreateSpeedBucket, you only need to specify the type element. All other parameters will be generated.


Requests

Example GetSegmentsInBox Request
Query
http://{serverPath}.INRIX.com/...?Action=Action=CreateSpeedBucket&Token={token}&Name=testAddSpeedBucket&Description=This%20is%20a%20test&SpeedBucketXML=%3CSpeedBucket%20type%3D%221%22%3E%0A%3CRoadClosure%20penStyle%3D%222%22%20backColor%3D%22brown%22%20foreColor%3D%22white%22%20hatchStyle%3D%22Percent50%22%20%2F%3E%0A%3CBuckets%3E%0A%3CBucket%20num%3D%220%22%20min%3D%220%22%20max%3D%2231%22%20penStyle%3D%221%22%20backColor%3D%22black%22%20penWidthPercent%3D%2290%22%2F%3E%0A%3CBucket%20num%3D%221%22%20min%3D%2232%22%20max%3D%2262%22%20penStyle%3D%221%22%20backColor%3D%22Red%22%20%2F%3E%0A%3CBucket%20num%3D%222%22%20min%3D%2263%22%20max%3D%2292%22%20penStyle%3D%221%22%20backColor%3D%22Yellow%22%20%2F%3E%0A%3CBucket%20num%3D%223%22%20min%3D%2293%22%20max%3D%22100%22%20penStyle%3D%221%22%20backColor%3D%22ForestGreen%22%20%2F%3E%0A%3C%2FBuckets%3E%0A%3C%2FSpeedBucket%3E 

Note: The XML for the SpeedBucketXML parameter is URL-encoded before being passed to CreateSpeedBucket. This is not required, but it is recommended.
Here is the SpeedBucketXML parameter value, not URL-encoded:
<SpeedBucket type="1">
  <RoadClosure penStyle="2" backColor="brown" foreColor="white" hatchStyle="Percent50" />
  <Buckets>
    <Bucket num="0" min="0" max="31" penStyle="1" backColor="black" penWidthPercent="90"/>
    <Bucket num="1" min="32" max="62" penStyle="1" backColor="Red" />
    <Bucket num="2" min="63" max="92" penStyle="1" backColor="Yellow" />
    <Bucket num="3" min="93" max="100" penStyle="1" backColor="ForestGreen" />
  </Buckets>
</SpeedBucket>

Responses

200 Success 
<Inrix docType="CreateSpeedBucket" copyright="Copyright INRIX Inc." versionNumber="4.4" createdDate="2013-02-06T19:02:27Z" statusId="0" statusText="" responseId="4cd2a19f-c79a-45ff-8cfb-5735b18eb86f">
    <SpeedBuckets>
        <SpeedBucket type="1" id="641126130" name="testAddSpeedBucket" description="This is a test" private="false" createTime="2013-02-07T03:02:27Z">
            <RoadClosure penStyle="2" backColor="brown" foreColor="white" hatchStyle="Percent50" />
            <Buckets>
                <Bucket num="0" min="0" max="31" penStyle="1" backColor="black" penWidthPercent="90" />
                <Bucket num="1" min="32" max="62" penStyle="1" backColor="Red" />
                <Bucket num="2" min="63" max="92" penStyle="1" backColor="Yellow" />
                <Bucket num="3" min="93" max="100" penStyle="1" backColor="ForestGreen" />
            </Buckets>
        </SpeedBucket>
    </SpeedBuckets>
</Inrix>

/?Action=GetSpeedBucket

GET Returns a speed bucket or all speed bucket definitions for vendor group.

Parameters

  = required
Name Located In Type Description
action Query String Use GetSpeedBucket
Token Query String A valid authorization token returned in response to a GetSecurityToken request.
SpeedBucketID Query Integer The ID of the speed bucket to retrieve, returned from a previous call to CreateSpeedBucket. If left blank all SpeedBucketIDs created using these credentials are returned.

Requests

Example GetSpeedBucket Request
Query
http://{serverPath}.INRIX.com/...?Action=GetSpeedBucket&Token={token}&SpeedBucketID=641126130

Responses

200 Success 
<Inrix docType="GetSpeedBucket" copyright="Copyright INRIX Inc." versionNumber="4.4" createdDate="2013-02-06T19:02:27Z" statusId="0" statusText="" responseId="4cd2a19f-c79a-45ff-8cfb-5735b18eb86f">
    <SpeedBuckets>
        <SpeedBucket type="1" id="641126130" name="testAddSpeedBucket" description="This is a test" private="false" createTime="2013-02-07T03:02:27Z">
            <RoadClosure penStyle="2" backColor="brown" foreColor="white" hatchStyle="Percent50" />
            <Buckets>
                <Bucket num="0" min="0" max="31" penStyle="1" backColor="black" penWidthPercent="90" />
                <Bucket num="1" min="32" max="62" penStyle="1" backColor="Red" />
                <Bucket num="2" min="63" max="92" penStyle="1" backColor="Yellow" />
                <Bucket num="3" min="93" max="100" penStyle="1" backColor="ForestGreen" />
            </Buckets>
        </SpeedBucket>
    </SpeedBuckets>
</Inrix>

/?Action=UpdateSpeedBucket

GET Edits an exisiting speed bucket based on a specified SpeedbucketID.

Parameters

  = required
Name Located In Type Description
action Query String Use UpdateSpeedBucket
Token Query String A valid authorization token returned in response to a GetSecurityToken request.
SpeedBucketID Query String The ID of the speed bucket to update, returned from a previous call to CreateSpeedBucket.
Name Query String The name of the speed bucket.
Description Query String A textual description of the speed bucket.
Private Query Boolean Specifies whether the bucket is accessible by all vendors in the group, or only the defining vendor. The default is false.
Value Description
true The bucket cannot be viewed or used by any other vendor in the group.
false (default) The bucket can be viewed and used by other vendors in the same vendor group. It cannot be viewed or used by any vendors in another vendor group.
SpeedBucketXML Query String An XML definition of INRIX speed bucket. Only the type attribute is specified; the other attributes are generated when the speed bucket is created.
Value Type Description
type Attribute (integer) The type of speed bucket.
Value Description
1 Congestion: Current speed as a percentage of the free flow or reference speed. For example, the four buckets defined in the INRIX speed bucket ID 1 are represented as:
  1. Color = black if speed is 0-31% of free flow speed.
  2. Color = red if speed is 32-62% of free flow speed.
  3. Color = yellow if speed is 63-92% of free flow speed.
  4. Color = forestgreen if speed is 93-100% of free flow speed.
2 Speed: The absolute current reported speeds in mph or kph. For example, you might have a bucket defined as:
  1. Color = black if speed is 0-15 MPH.
  2. Color = red if speed is 16-30 MPH.
  3. Color = yellow if speed is 31-40 MPH.
  4. Color = green if speed is 41+.
3 Relative Speed: The absolute difference between the current reported speed (mph or kph) and the typical speed for the current time of day and day of week.
4 Relative Congestion: The percentage difference between the current congestion (current speed versus free flow speed) and the typical congestion for the current time of day and day of week (typical speed versus free flow speed).
id Attribute (integer) The ID of the speed bucket.
name Attribute (string) The name of the speed bucket.
description Attribute (string) A description of the speed bucket.
private Attribute (boolean) Whether the speed bucket is private or available to the public.
createTime Attribute (DateTime) When the speed bucket was created.
RoadClosure Element Information for how a road closure is displayed. Note that pen colors can be either .NET Color Names or ARGB color values in standard web format (e.g., '#00112233').
Name Type Description
penStyle Attribute (integer) The style of the pen used to draw the section of road. 1 for solid; 2 for hatched.
backColor Attribute (string) The color for solid pens, and the background color for hatched pens. See Notes below for format.
foreColor Attribute (string) The accent color for hatched pens. See Notes below for format.
hatchStyle Attribute (string) The style of hatched pens. See .NET hatch styles for values.
penWidthPercent Attribute (integer) The percentage of the pen width used for drawing the road.
Buckets Element A collection of buckets that defines how groups of speeds are displayed. Note that pen colors can be either .NET Color Names or ARGB color values in standard web format (e.g., '#00112233').
Name Type Description
Bucket Element Data on how a range of speed data is displayed.
Name Type Description
num Attribute (integer) The index of the bucket in the series of bucket elements.
min Attribute (integer) The minimum value for data that goes into this bucket.
max Attribute (integer) The maximum value for data that goes into this bucket.
penStyle Attribute (integer) The style of the pen used to draw the section of road. 1 for solid; 2 for hatched.
backColor Attribute (string) The color for solid pens, and the background color for hatched pens. See Notes below for format.
foreColor Attribute (string) The accent color for hatched pens. See Notes below for format.
hatchStyle Attribute (string) The style of hatched pens. See .NET hatch styles for values.
penWidthPercent Attribute (integer) The percentage of the pen width used for drawing the road.

Notes

Speed buckets are ranges of speeds or percentages used to qualify TMC data, providing a high level view of congestion or speed. Previously these buckets were predetermined by INRIX. You can use the speed bucket API to set your own ranges or “buckets” for use with the TMC speed APIs and the tile server. There are four types of speed buckets that you can create, as shown below, with their type values:

  1. Congestion: Current speed as a percentage of the free flow or reference speed. For example, the four buckets defined in the INRIX speed bucket ID 1 are represented as:
    1. Color = black if speed is 0-31% of free flow speed.
    3. Color = red if speed is 32-62% of free flow speed.
    4. Color = yellow if speed is 63-92% of free flow speed.
    5. Color = forestgreen if speed is 93-100% of free flow speed.
  2. Speed: The absolute current reported speeds in mph or kph. For example, you might have a bucket defined as:
    1. Color = black if speed is 0-15 MPH.
    2. Color = red if speed is 16-30 MPH.
    3. Color = yellow if speed is 31-40 MPH.
    4. Color = green if speed is 41+.
  3. Relative Speed: The absolute difference between the current reported speed (mph or kph) and the typical speed for the current time of day and day of week.
  4. Relative Congestion: The percentage difference between the current congestion (current speed versus free flow speed) and the typical congestion for the current time of day and day of week (typical speed versus free flow speed).

All vendors have access to the six pre-defined INRIX speed buckets. These speed buckets are represented by SpeedBucketIDs 1-6. You can retrieve definitions of each of these speed buckets by calling GetSpeedBucket with SpeedBucketID set to one of these six values. Call GetSpeedBucket with no speedbucketID to list all the available values.


Requests

Example UpdateSpeedBucket Request
Query
http://{serverPath}.INRIX.com/...?Action=UpdateSpeedBucket&Token={token}&SpeedBucketID=641126130Name=newTestAddSpeedBucket&SpeedBucketXML=%3CSpeedBucket%20type%3D%221%22%3E%0A%3CRoadClosure%20penStyle%3D%222%22%20backColor%3D%22brown%22%20foreColor%3D%22white%22%20hatchStyle%3D%22Percent50%22%20%2F%3E%0A%3CBuckets%3E%0A%3CBucket%20num%3D%220%22%20min%3D%220%22%20max%3D%2231%22%20penStyle%3D%221%22%20backColor%3D%22black%22%20penWidthPercent%3D%2290%22%2F%3E%0A%3CBucket%20num%3D%221%22%20min%3D%2232%22%20max%3D%2262%22%20penStyle%3D%221%22%20backColor%3D%22Red%22%20%2F%3E%0A%3CBucket%20num%3D%222%22%20min%3D%2263%22%20max%3D%2292%22%20penStyle%3D%221%22%20backColor%3D%22Yellow%22%20%2F%3E%0A%3CBucket%20num%3D%223%22%20min%3D%2293%22%20max%3D%22100%22%20penStyle%3D%221%22%20backColor%3D%22ForestGreen%22%20%2F%3E%0A%3C%2FBuckets%3E%0A%3C%2FSpeedBucket%3E

Note: The XML for the SpeedBucketXML parameter is URL-encoded before being passed to UpdateSpeedBucket. This is not required, but it is recommended.

Responses

200 Success 
<Inrix docType="UpdateSpeedBucket" copyright="Copyright INRIX Inc." versionNumber="2.1.0" createdDate="2009-03-04T01:23:55Z" statusId="0" statusText="" responseId="70ce0c34-2237-4100-afe0-363fbdb16824">
    <SpeedBuckets>
        <SpeedBucket type="1" id="641126130" name="newTestAddSpeedBucket" description="This is a test" private="false" createTime="2013-02-07T03:02:27Z">
            <RoadClosure penStyle="2" backColor="brown" foreColor="white" hatchStyle="Percent50" />
            <Buckets>
                <Bucket num="0" min="0" max="31" penStyle="1" backColor="black" penWidthPercent="90" />
                <Bucket num="1" min="32" max="62" penStyle="1" backColor="Red" />
                <Bucket num="2" min="63" max="92" penStyle="1" backColor="Yellow" />
                <Bucket num="3" min="93" max="100" penStyle="1" backColor="ForestGreen" />
            </Buckets>
        </SpeedBucket>
    </SpeedBuckets>
</Inrix>

/?Action=DeleteSpeedBucket

GET Removes a speed bucket based on a specified SpeedbucketID.

Parameters

  = required
Name Located In Type Description
action Query String Use DeleteSpeedBucket
Token Query String A valid authorization token returned in response to a GetSecurityToken request.
SpeedBucketID Query Integer The ID of the speed bucket to delete, returned from a previous call to CreateSpeedBucket.

Requests

Example DeleteSpeedBucket Request
Query
http://{serverPath}.INRIX.com/...?Action=DeleteSpeedBucket&Token={token}&SpeedBucketID=259703192

Responses

200 Success 
<Inrix docType="DeleteSpeedBucket" copyright="Copyright INRIX Inc." versionNumber="2.1.0" createdDate="2009-03-04T01:28:40Z" statusId="0" statusText="" responseId="a415dba3-66f9-42b0-948e-2da8f3bc4b67">
    <InputParameters>
        <InputParameter name="action" value="deletespeedbucket" />
        <InputParameter name="token" value="{tokenvalue}" />
        <InputParameter name="speedbucketid" value="259703192" />
    </InputParameters>
</Inrix>