INRIX IQ logo

ANALYTICS

Trade Area Trips

The Trade Areas Trips API is a way to quickly query a year of trip origins and destinations over a small geographical area.

Overview

The Trade Areas Trips API returns the start and endpoints of a year of trips for a location specified by either a point-radius, a rectangular lat/long box, or a lat/long polygon. If you specify that the location is the Origin, the query returns all trips that began there. If you specify the Destination, the query returns all trips that ended there. The query area limit is 1 sq. mile.

The API returns rich trip metadata (start/end location, start/end time, device id, trip distance, trip mean speed) in json format. The query results are paginated, so full results are retrieved by calling the API multiple times with a limit of 10000 records returned with each page. Each query typically takes 1.5 seconds. A separate (and faster) Trips Count API returns the total trip count for the query, so total the number of records and pages can be known in advance.

Trip data will be updated quarterly, and the system will always contain 12 consecutive months of data. The default query returns the full 12 months of data, although custom time range queries are supported. All trip records are reported in UTC time.

Response Data

The INRIX Trade Area Trips API requests returns metadata for all the trips matching the query:


Description: Finds INRIX trips that start or end within the specified region.

https://trade-areas-api.inrix.com/v1/trips

GET Gets trips that either start or end within the specified region.

Parameters

  = required
Name Located In Type Description
Authorization Header String A valid bearer access token provided from the GET appToken API response. The token must be added to the request header using the format 'Authorization: Bearer xxxx.xxx.xxxx'.
od Query String Determines whether to search for trips by origin or destination; only one type of search can be done at a time.
Value Description
origin The query geometry is the origin: find trips that start inside it.
destination The query geometry is the destination: find trips that end inside it.
either The query geometry is either the origin or destination: find trips that start or end inside it.
geoFilterType Query String Determines the query geometry (either a circle, rectangular bounding box, or a polygon)
Value Description
circle requires one point and a radius
bbox requires two points: TOP LEFT, then BOTTOM RIGHT
polygon requires at least three points listed COUNTER-CLOCKWISE
radius Query Double radius is only used with the circle geoFilterType. Specify radius as a double with a unit of: km, mi, ft, m (e.g., 0.2km, 1000ft). The minimum radius is 10m and the maximum radius (set by the 1 sq mi limit) is 0.907km).
points Query String One or more points are needed for every query. The format is lat|long and multiple points separated by commas: lat1|long1,lat2|long2,lat3|long3. Be sure to list bbox corners in TopLeft, Bottom Right order. Be sure to list polygon points counter-clockwise.
limit Query Double Refers to page size for pagination (there is no limit on the number of results returned either by count or by trip distance). This parameter specifies the page size. The default is 1000 trips, the minimum is 10 trips, and the maximum is 10000 trips. The fast trips-count API can be used to precalculate the total number of pages needed (and it ignores this parameter).
providerType Query String Limits the query to fleet or consumer trips only.
Value Description
fleet fleet includes private trucking fleets, for hire vehicles, local delivery fleets, field service vehicles, taxis
consumer consumer includes only consumer vehicles
startDateTime Query String Enables searches for trips that begin within a specified time range. By default the API returns all trips for a full year (12 consecutive months), but this parameter provides more fine-grained control. You may use one or two comparison operations (>,>=,<,<=) and they must be url encoded. The time is in UTC and its format is yyyy-MM-ddTHH:mm
Value Description
%3E > (greater than) Example: startDateTime=%3E2016-07-01T02:31
%3E%3D >= (greater than or equal to) Example: startDateTime=%3E%3D2016-07-01T02:31
%3C < (less than) Examples: startDateTime=%3C2016-07-01T02:31
%3C%3D <= (less than or equal to) Example: startDateTime=%3C%3D2016-07-01T02:31
endDateTime Query String Enables searches for trips that end within a specified time range. By default the API returns all trips for a full year (12 consecutive months), but this parameter provides more fine-grained control. You may use one or two comparison operations (>,>=,<,<=) and they must be url encoded. The time is in UTC and its format is yyyy-MM-ddTHH:mm
Value Description
%3E > (greater than) Example: startDateTime=%3E2016-07-01T02:31
%3E%3D >= (greater than or equal to) Example: startDateTime=%3E%3D2016-07-01T02:31
%3C < (less than) Examples: startDateTime=%3C2016-07-01T02:31
%3C%3D <= (less than or equal to) Example: startDateTime=%3C%3D2016-07-01T02:31
endpointType Query String Limits the query to one value of endpointType
Value Description
3 An endpointType of 3 indicates that INRIX observed that the device was stationary at the start and end of the trip, which is the ideal case.
2 An endpointType of 2 indicates that INRIX observed that the device was stationary at the end of the trip.
1 An endpointType of 1 indicates that INRIX observed that the device was stationary at the start of the trip.
0 An endpointType of 0 indicates that INRIX did not observe that the device was stationary at either the start or the end of the trip. The trip may or may not have actually ended in this location, but no more data was available to decide.
tripDistanceMeters Query String Enables searches for trips within a specified distance range in meters. By default the API returns trips with any trip distance, but this parameter provides more fine-grained control. You may use one or two comparison operations (>,>=,<,<=) and they must be url encoded.
Value Description
%3E > (greater than) Example: tripDistanceMeters=%3E1000
%3E%3D >= (greater than or equal to) Example: tripDistanceMeters=%3E%3D1000
%3C < (less than) Examples: tripDistanceMeters=%3C1000
%3C%3D <= (less than or equal to) Example: tripDistanceMeters=%3C%3D1000
fields Query String Limits the response fields. This parameter can specify a single field, or multiple fields in a comma-separated list such as “startLoc,endLoc”. By default the API returns all the fields.
Value Description
tripId Unique anonymized ID for the trip
providerHash Unique anonymized ID for the source of the trip data
startDateTime UTC timestamp for the start of the trip
endDateTime UTC timestamp for the end of the trip
startLoc Latitude and Longitude of the start of the trip
endLoc Latitude and Longitude of the end of the trip
deviceId Unique anonymized ID for the device/vehicle that reported the trip data
tripDistanceMeters the total trip distance in meters
tripMeanSpeedKPH the mean speed of the trip in kilometers per hour
endpointType indicates whether or not INRIX observed that the device was stationary at the start/end/both/neither for the trip

Requests

Example Find trips within a polygon and limit results pages size to 1000 trips per page.
Query
https://trade-areas-api.inrix.com/v1/trips?geoFilterType=polygon&od=origin&points=47.611512|-122.340262,47.609197|-122.338718,47.607809|-122.334083,47.612669|-122.331422,47.614926|-122.334168&limit=1000

Responses

200 Success 
{
    "data": [
        {
            "providerHash":"f033ab37c30201f73f142449d037028d",
            "startLoc":"26.0727,-80.18358",
            "startDateTime":"2016-07-01T03:43:02.000Z",
            "endLoc":"26.09042,-80.15962",
            "tripDistanceMeters":3276,
            "tripMeanSpeedKPH":35,
            "tripId":"d304a477deb63b9ddfa415695af402a9",
            "endDateTime":"2016-07-01T03:48:40.000Z",
            "deviceId":"752afa02753ccbc8dcf7cdae76cd878f",
            "providerType":"fleet",
            "endpointType": 3
        },
        {
            "providerHash":"f033ab37c30201f73f142449d037028d",
            "startLoc":"26.09042,-80.15962",
            "startDateTime":"2016-07-01T03:48:41.000Z",
            "endLoc":"27.16223,-80.22586",
            "tripDistanceMeters":129760,
            "tripMeanSpeedKPH":88,
            "tripId":"a9a3e3e2fa965b080502ccf80bfe08e8",
            "endDateTime":"2016-07-01T05:16:40.000Z",
            "deviceId":"752afa02753ccbc8dcf7cdae76cd878f",
            "providerType":"fleet",
            "endpointType": 0
        },
            ],
    "paging":{
        "nextCursor": "https://trade-areas-api.inrix.com/v1/trips?geoFilterType=polygon&od=origin&points=47.611512|-122.340262,47.609197|-122.338718,47.607809|-122.334083,47.612669|-122.331422,47.614926|-122.334168&limit=1000&cursorNext=1467355362000%2C364342991863"
    }
}

Response Elements

Property Type Description
tripId String Unique anonymized ID for the trip
providerHash String Unique anonymized ID for the source of the trip data
startDateTime String UTC timestamp for the start of the trip
endDateTime String UTC timestamp for the end of the trip
startLoc String Latitude and Longitude of the start of the trip
endLoc String Latitude and Longitude of the end of the trip
deviceId String Unique anonymized ID for the device/vehicle that reported the trip data
tripDistanceMeters Double the total trip distance in meters
tripMeanSpeedKPH Double the mean speed of the trip in kilometers per hour
endpointType Int indicates whether or not INRIX observed that the device was stationary at the start/end/both/neither for the trip
nextCursor String a URL for the next page of results (if any) for the current query

https://trade-areas-api.inrix.com/v1/trips-count

GET Identical query syntax, but returns only the total count of the matching trips

Requests

Example Counts INRIX trips that start or end within the specified region.
Query
https://trade-areas-api.inrix.com/v1/trips-count?geoFilterType=polygon&od=origin&points=47.611512|-122.340262,47.609197|-122.338718,47.607809|-122.334083,47.612669|-122.331422,47.614926|-122.334168&limit=1000

Responses

200 Success 
{
    "count": "12537"
}

Response Elements

Property Type Description
count String the total number of trips matching the query parameters