queryType: getRegionalDomicileAnalytics*
The getRegionalDomicileAnalytics queryType is used to evaluate vehicle movements roundtrip from a domicile (or place the vehicle resides).
See Special Case APIs for more information.
Parameters
These parameters should be passed to the functionParameters object regardless of which method you choose to make an API request.
| Parameter | Description | Type | Defined Value Set | Value Req'd |
|---|---|---|---|---|
| dateRange |
An object defining the analysis date range. Each object contains:
Note:
The maximum date range is one year. For the purposes of determining the domicile for a vehicle, a minimum of one month back from the “DateTo” date is utilized. If the date range exceeds one month, the full date range is used for domicile calculation. | OBJECT | - | Y |
| eligibilityCriteria |
An object that defines the eligibility criteria to be applied for an analysis. Pass null if you wish to run without eligibility. The object contains:
| OBJECT | - | N |
| fuelTypes | An array of strings representing the fuel types you want analyzed. Possible values are "Diesel", "Electric", "Flexible", "Gasoline", "Hybrid", "Other" and "Unknown". Refer to the Fuel types table for a description of each option. Can send an empty array to return all fuel types. | ARRAY | See Fuel types for a list of fuel types | - |
| isMetric | True if you want the data returned to be metric, false if you want imperial. | BOOLEAN | true or false | Y |
| minDomicileDutyCycleDistance |
The minimum distance of a domicile duty cycle for it to be utilized in analysis calculations. Domicile duty cycles shorter than this value will be excluded from the analysis. Note:
To consider all domicile duty cycles, set this value to 0. The default value for this parameter is 0. | FLOAT | - | N |
| minDomicileStopDuration |
The minimum stop duration (minutes) at the vehicle’s domicile to be considered a domicile stop and the end of a domicile duty cycle. Domicile stops shorter than this input value are chained to the proceeding trip, thereby ensuring that a domicile duty cycle will only complete when a vehicle stops at its domicile for longer than this value. Note:
To consider all domicile stops, set this value to 0. The default value for this parameter is 0. See definition of a stop. | INTEGER | - | N |
| NAICS | An array of integers representing industry IDs. Can pass an empty array to return data for all industries. To get a list of available industries, use the getIndustries API. | ARRAY | - | N |
| percentiles | Array of integers representing what percentiles you want the metrics broken up into. Default if not provided is [15,85]. | ARRAY | [1-99] | N |
| queryType | Must equal getRegionalDomicileAnalytics. | STRING | "getRegionalDomicileAnalytics" | Y |
| vehicleClasses |
An array of vehicle class objects where each object contains | ARRAY |
See the Vehicle types and Weight class tables. For Vehicle Type: "Truck", "Passenger", "MPV", "Bus", "Other". More information at AFDC Vehicle Categories. To get all vehicle types, pass an empty array. | N |
| vehicleClassSchemeId | Determines which vehicle classification scheme you will receive data for. See the Vehicle class schemas for a list of options. The default value is 2. | INTEGER | [1,4] | N |
| vocations | An array of integers representing vocation IDs for vocations of interest. Can pass specific IDs or an empty array to return data for all vocations. | ARRAY | See Vocation descriptions for a list of vocation IDs and their mapping information. | N |
| zones |
An array of objects representing the zones for which you want information. Each object contains
| ARRAY |
See Zones for details on how to structure the zone inputs for each zone type. | Y |
Responses
| Code | Type | Description |
|---|---|---|
| 200 | JSON | The requested data. |
| 401 | JSON | Occurs for various unauthorized tasks, such as not providing credentials in your parameters. |
| 500 | JSON | Occurs if an internal server error occurs. Contact Altitude Support if this occurs. |
Response Schema
| Attribute | Description | Data Type | Defined Value Set |
|---|---|---|---|
| DomDCCount | Total number of domicile duty cycles for eligible vehicles that have their domicile in the region, calculated as a summation of domicile duty cycles across all eligible vehicles. | INTEGER | - |
| DomDCDistanceAvg | The average domicile duty cycle distance (kilometers or miles). | FLOAT | - |
| DomDCDistanceMed | The median domicile duty cycle distance (kilometers or miles). | FLOAT | - |
| DomDCDistancePercentiles |
Array of objects representing percentile domicile duty cycle distance values for input percentiles. Each object contains:
Note:
If no percentiles are input, the 15th and 85th percentiles are provided by default. Percentiles will only be provided if there are sufficient records to calculate the requested percentiles. | ARRAY | - |
| DomDCDistanceStdev | The standard deviation of domicile duty cycle distance (kilometers or miles). | FLOAT | - |
| DomDCDurationAvg | The average domicile duty cycle duration (minutes). | FLOAT | - |
| DomDCDurationMed | The median domicile duty cycle duration (minutes). | FLOAT | - |
| DomDCDurationPercentiles |
Array of objects representing percentile domicile duty cycle duration values for input percentiles. Each object contains:
Note:
If no percentiles are input, the 15th and 85th percentiles are provided by default. Percentiles will only be provided if there are sufficient records to calculate the requested percentiles. | ARRAY | - |
| DomDCDurationStdev | The standard deviation of domicile duty cycle duration (minutes). | FLOAT | - |
| DomMetricsByDayOfWeek |
Array of objects representing domicile metrics for a day of week, based on domicile duty cycles that stop at their domicile during the day of the week (local time). Note:
Exception on Each object contains:
| ARRAY | DayOfWeek = [1:7], where 1 = Sunday and 7 = Saturday. |
| DomMetricsByFuelType |
Array of objects representing domicile metrics for each fuel type. Each object contains:
| ARRAY | - |
| DomMetricsByHour |
Array of objects representing domicile metrics for an hour, based on domicile duty cycles that stop at their domicile during the hour (local time). Note:
Exception on Each object contains:
| ARRAY | Hour — [0:23] |
| DomMetricsByIndustry |
Array of objects representing domicile metrics for each NAICS code 1. Each object contains:
| ARRAY | - |
| DomMetricsByMonth |
Array of objects representing domicile metrics for a month, based on domicile duty cycles that stop at their domicile during the month (local time). Note:
Exception on Each object contains:
| ARRAY | Month — [1:12] |
| DomMetricsByVehicleClass |
Array of objects representing domicile metrics for each vehicle class. Each object contains:
| ARRAY | - |
| DomMetricsForVehicleDailyDC |
An object representing metrics around the average daily domicile duty cycle for a vehicle. The object contains:
| ARRAY | - |
| DomMetricsByVocation |
Array of objects representing domicile metrics for each vocation. Each object contains:
| ARRAY | - |
| DomStopDurationAvg | The average domicile stop duration (minutes). | FLOAT | - |
| DomStopDurationMed | The median domicile stop duration (minutes). | FLOAT | - |
| DomStopDurationPercentiles |
Array of objects representing percentile domicile stop duration values for input percentiles. Each object contains:
Note:
If no percentiles are input, the 15th and 85th percentiles are provided by default. Percentiles will only be provided if there are sufficient records to calculate the requested percentiles. | ARRAY | - |
| DomStopDurationStdev | The standard deviation of domicile stop duration (minutes). | FLOAT | - |
| EligibleDomVehicleCount | The number of vehicles that meet vehicle filters, have their domicile in the zone and are also deemed eligible for the analysis period based on input eligibility criteria. | INTEGER | - |
| ISO_3166_2 | Unique ISO 3166-2 identifier representing the state/provincial code of the region. | STRING | - |
| NonDomStopDurationAvg | The average stop duration (minutes) for stops made at non-domiciles during a domicile duty cycle. | FLOAT | - |
| NonDomStopDurationMed | The median stop duration (minutes) for stops made at non-domiciles during a domicile duty cycle. | FLOAT | - |
| NonDomStopDurationPercentiles |
Array of objects representing percentile non domicile stop duration values for input percentiles. Each object contains:
Note:
If no percentiles are input, the 15th and 85th percentiles are provided by default. Percentiles will only be provided if there are sufficient records to calculate the requested percentiles. | ARRAY | - |
| NonDomStopDurationStdev | The standard deviation of stop duration (minutes) for stops made at non-domiciles during a domicile duty cycle. | FLOAT | - |
| NonDomStopsPerDomDCAvg | The average number of non-domicile stops per domicile duty cycle. | INTEGER | - |
| NonDomStopsPerDomDCMed | The median number of non-domicile stops per domicile duty cycle. | INTEGER | - |
| NonDomStopsPerDomDCPercentiles |
Array of objects representing percentile non domicile stops per domicile duty cycle values for input percentiles. Each object contains:
Note:
If no percentiles are input, the 15th and 85th percentiles are provided by default. Percentiles will only be provided if there are sufficient records to calculate the requested percentiles. | ARRAY | - |
| NonDomStopsPerDomDCStdev | The standard deviation of non-domicile stops per domicile duty cycle. | INTEGER | - |
| TotalDomVehicleCount | The number of vehicles that meet vehicle filters and have their domicile within the zone. | INTEGER | - |
| ZoneDescription |
Description of the zone when available. The value is based on the type of zone:
| STRING | - |
| ZoneId | The zone ID for which data is being returned. | STRING | - |
| ZoneType | The zone type of the zone. | STRING | [“Custom”, ”State”, ”County”, City”, ”ZIP”, “CTR”,“FSA”, “TAZ] |
Sample parameters
{
"queryType": "getRegionalDomicileAnalytics",
"dateRange": {
"DateFrom": "2022-04-15",
"DateTo": "2022-04-30"
},
"eligibilityCriteria":{
"MaxDistanceThreshold": 300,
"PercentileThreshold": 0.95,
"MinDomicileDutyCycles": 2
},
"isMetric": false,
"minDomicileDutyCycleDistance": 2,
"minDomicileStopDuration": 30,
"percentiles": [10,20,30,40,50,60,70,80,90],
"vehicleClassSchemeId": 2,
"zones": [{
"ZoneId": "32003",
"ISO_3166_2": "US-NV",
"ZoneType": "County"
}]
}