POI Location Specific Insights API

POI Location Specific Insights (POI LSI) is an Altitude module that enables operators to evaluate the competitive landscape around any specific location using first-party commercial vehicle telematics.

What is POI Location Specific Insights?

Given a location and a radius, POI LSI returns all competitor points of interest (POIs) within that radius, including brand names, stop counts, dwell-time distribution, vehicle class, vocation, fleet size, and fuel type, so operators can benchmark a site against its competitive environment using the same commercial vehicle data that powers Altitude's Stop Analytics module.

POI LSI is purpose-built for site-level analysis. Every query is anchored to a specific location and bounded by a radius. The module does not support brand-level national queries or corridor-based analysis in Phase 1.

Who is it for?

POI LSI is designed for petroleum and gas operators, network planners, and commercial site developers who make multi-million-dollar site investment, expansion, and competitive-monitoring decisions. In Phase 1, the module is delivered as an API. A visual layer for lower-fluency users is planned for a future release through Altitude Lens.

Endpoints


Operation	Endpoints	Description
getPointsOfInterest	POST /api/v2/poi/locations · GET /api/v2/jobs/{id} · GET /api/v2/poi/locations/{id}	Returns all POI locations within contracted categories and purchased geographies. Returns `id` values to pass in the `locationIds` parameter of the summary or analytics endpoints.
getPOISummary	POST /api/v2/poi/summary · GET /api/v2/jobs/{id} · GET /api/v2/poi/summary/{id}	Lightweight competitor list around an anchor location: brand names, location count, density, and coordinates. Use it as the first step before committing to a full analytics query. Accepts `locationIds` from getPointsOfInterest.
getPOIAnalytics	POST /api/v2/poi/analytics · GET /api/v2/jobs/{id} · GET /api/v2/poi/analytics/{id} · GET /api/v2/poi/analytics/{id}/time-series	Full per-location commercial vehicle metrics: stop count, dwell distribution, vehicle class, vocation, fleet size, fuel type, and trade-area total. Supports time-series generation. Accepts `locationIds` from getPointsOfInterest.
getIndustries	GET /api/v2/filters/naics	Returns the industry categories available to the database, including which are licensed for POI use. See the General API Module for full documentation.

Supporting: getDatabaseInfo (GET /api/v2/databases/config) returns poiNaicsAllowed, the categories licensed for POI on this database. See the General API Module for full documentation.

Workflow

POI LSI analysis follows a two-step async workflow: discover locations with getPointsOfInterest, then analyze with getPOISummary or getPOIAnalytics. Each analysis POST returns HTTP 202 and a JobStatusDto. Poll GET /api/v2/jobs/{id} until the job completes, then retrieve results via GET. Result endpoints are paginated.

Methodology

POI LSI uses Altitude's POI location data to identify competitor points of interest, and Altitude's commercial vehicle telematics to supply the stop-event metrics at each location. Stop events are attributed to POIs using an anchor-tenant model over purpose-built site catchments. Roughly 40-50% of commercial vehicle stops are attributed to a specific POI, with the remainder occurring at private and non-POI destinations. For the full explanation, see the POI LSI Methodology page in the User Guide.

getPointsOfInterest

getPointsOfInterest returns all POI locations within the database's contracted categories and purchased geographies.

Overview

Use this endpoint to enumerate the locations available to you before calling getPOISummary or getPOIAnalytics. It is also the appropriate endpoint for workflows that monitor for new competitor locations over time, run it on a regular cadence and diff against your previous results to detect openings and closures.

A category filter is required. You cannot retrieve all POIs across all categories in a single call; Altitude enforces this requirement to comply with POI data licensing terms.

Endpoints and flow

POST /api/v2/poi/locations (submit) → GET /api/v2/jobs/{id} (poll status) → GET /api/v2/poi/locations/{id} (retrieve results).

Parameters


Parameter	Type	Required	Description
`asOfDate`	STRING	Yes	The POI snapshot date to use, the first day of the last month in your intended date range, in YYYY-MM-DD format. Use this to retrieve the POI snapshot that matches your analytics query window. The POI snapshot refreshes monthly.
`naicsLevel2`	ARRAY	Yes	Category codes to return (maximum 2). Must be codes licensed for POI use on this database. Use getDatabaseInfo to retrieve your licensed categories, or getIndustries to see all available categories with their `isPurchasedForPOI` flag. A gas-station query also returns convenience stores that sell fuel, automatically.
`zones`	ARRAY	Yes	One or more zone objects defining the geographic scope of the query. Each zone object contains `code`, `iso_3166_2`, and `type`. Supported types: Custom, State, County, City, TAZ, ZIP, CTR, and FSA. Example: `{ code: "32003", type: "County", iso_3166_2: "US-NV" }`

Response fields


Field	Type	Description
`brands`	ARRAY	Brand name or names associated with this POI.
`isOwned`	BOOLEAN	Indicates whether this POI belongs to the same brand as the querying organization.
`latitude`	FLOAT	Centroid latitude of the POI location.
`longitude`	FLOAT	Centroid longitude of the POI location.
`iso_3166_2`	STRING	ISO 3166-2 state or province code for this location.
`id`	STRING	Unique identifier for this POI location. Use this value in the `locationIds` parameter of getPOISummary and getPOIAnalytics.
`name`	STRING	Descriptive name for this POI location.
`naics`	OBJECT	Category code and description for this location. Contains `code` (integer) and `description` (string).

Usage notes

Use getPointsOfInterest to build a working list of id values, then pass those values in the locationIds parameter of subsequent getPOISummary or getPOIAnalytics calls.
For competitive monitoring workflows, run this endpoint on a regular cadence (quarterly is typical) and compare results against your previous pull to identify new entrants and closures.
The asOfDate parameter should match the start of the date range you intend to query in getPOIAnalytics. Because the POI snapshot refreshes monthly, re-validate your id values monthly; a mismatched date may return POIs that have since changed category or closed.

getPOISummary

getPOISummary returns a lightweight competitor list around an anchor POI: brand names, location count, competitor density, and coordinates.

Overview

getPOISummary is designed to be the first step in a site evaluation workflow. Use it to understand the competitive landscape before committing to the heavier getPOIAnalytics query. The summary endpoint is fast and low-cost by design. At a 25-mile radius, a typical travel-center location may have 50 or more competitor sites; getPOISummary surfaces all of them with brand names and positions quickly, allowing you to decide which subset warrants deeper analytics.

Endpoints and flow

POST /api/v2/poi/summary (submit) → GET /api/v2/jobs/{id} (poll status) → GET /api/v2/poi/summary/{id} (retrieve results).

Parameters


Parameter	Type	Required	Description
`dateFrom`	STRING	Yes	First day of the analysis range, YYYY-MM-DD. Must be the first day of a fiscal month.
`dateTo`	STRING	Yes	Last day of the analysis range, YYYY-MM-DD. Must be the last day of a fiscal month. Supports a fiscal month, rolling quarter, or rolling year: minimum 1 month, maximum 12 months.
`naicsLevel2`	ARRAY	No	Filters results to the specified categories. If empty, all categories licensed for POI use on this database are included. A gas-station query also returns convenience stores that sell fuel, automatically.
`isMetric`	BOOLEAN	Yes	Must be false. POI LSI Phase 1 covers the US only; pass false. The km unit set is not available in Phase 1.
`radius`	FLOAT	Yes	Radius around the anchor POI. Accepted values: 5, 10, 15, 25, 75, 150. Units are miles. Maximum: 150 miles.
`locationIds`	ARRAY	Yes	Required array of POI location IDs returned by getPointsOfInterest. These IDs identify the anchor POI locations for the summary. Recommended ceiling: 20 per call. Note: Run getPointsOfInterest first, then pass the returned `id` values as `locationIds`.

Response fields


Field	Type	Description
`inputId`	STRING	ID of the anchor POI location.
`inputName`	STRING	Name of the anchor POI location.
`inputType`	STRING	Type of the input location. For POI queries, this is POI.
`input_iso_3166_2`	STRING	ISO 3166-2 code for the anchor POI location.
`naics`	OBJECT	Category code and description for the anchor POI. Contains `code` and `description`.
`brands`	ARRAY	Brand name or names of the anchor POI.
`competitorDensity`	INTEGER	Total number of competitor POI locations within the radius, in the same category as the anchor.
`isSourceLocation`	BOOLEAN	true if this row represents the anchor POI itself rather than a competitor.
`locationId`	STRING	Unique identifier for a competitor POI within the radius. Use this in getPOIAnalytics to request detailed metrics for this specific location.
`locationName`	STRING	Descriptive name of the competitor location.
`location_iso_3166_2`	STRING	ISO 3166-2 code for the competitor location.
`locationBrands`	ARRAY	Brand name or names of the competitor location.
`locationNaics`	OBJECT	Category code and description for the competitor location.
`locationLatitude`	FLOAT	Centroid latitude of the competitor location.
`locationLongitude`	FLOAT	Centroid longitude of the competitor location.
`locationIsOwned`	BOOLEAN	true if the competitor location belongs to the same brand as the anchor POI.

Usage notes

The recommended workflow is summary first, then analytics. Use getPOISummary to identify the competitor locationId values you want to analyze, then pass those in the locationIds parameter of getPOIAnalytics for full metrics. getPOISummary is significantly cheaper and faster than getPOIAnalytics.
Radius values are discrete, not free-form. Choose the radius that matches your competitive analysis question: 5-15 miles for urban or immediate-area analysis; 25-75 miles for regional or corridor benchmarking; 150 miles for regional market mapping.
The anchor POI itself appears in the response with isSourceLocation = true (and locationIsOwned = true when applicable) but is not counted in competitorDensity.

getPOIAnalytics

getPOIAnalytics returns full commercial vehicle metrics for all POI locations within a radius around an anchor location, including stop count, dwell-time distribution, vehicle class, vocation, fleet size, and fuel type.

Overview

The endpoint also supports time-series generation across month, week, day-of-week, and hourly aggregation units. It accepts one or more anchor zones per call.

Endpoints and flow

POST /api/v2/poi/analytics (submit) → GET /api/v2/jobs/{id} (poll status) → GET /api/v2/poi/analytics/{id} (retrieve primary results). When generateTimeSeries = true, retrieve the time series via GET /api/v2/poi/analytics/{id}/time-series using the job id returned from the run.

Parameters


Parameter	Type	Required	Description
`locationIds`	ARRAY	Yes	One or more POI location IDs (STRING) obtained from the `id` field of getPointsOfInterest. Recommended ceiling: 20 per call.
`radius`	FLOAT	Yes	Radius in miles around the anchor POI. Accepted values: 5, 10, 15, 25, 75, 150. POI LSI Phase 1 covers the US only; miles is the only applicable unit. Maximum: 150 miles.
`isMetric`	BOOLEAN	Yes	Must be false. POI LSI Phase 1 covers the US only; pass false. The km unit set is not available in Phase 1.
`dateFrom`	STRING	Yes	First day of the analysis range, YYYY-MM-DD. Must be the first day of a fiscal month.
`dateTo`	STRING	Yes	Last day of the analysis range, YYYY-MM-DD. Must be the last day of a fiscal month. Supports a fiscal month, rolling quarter, or rolling year: minimum 1 month, maximum 12 months.
`generateTimeSeries`	BOOLEAN	Yes	true to generate a time series alongside the primary response. The time series is retrieved separately via GET /api/v2/poi/analytics/{id}/time-series.
`aggregationUnits`	ARRAY	No	Which time-series aggregation units to generate. Accepted values: "month", "week", "dayofweek", "hour". Defaults to ["month","dayofweek"] if omitted; an empty array returns all. DayOfWeek is the recommended default.
`naicsLevel2`	ARRAY	No	Filters results to specified categories. If empty, all categories licensed for POI use are included. A gas-station query also returns convenience stores that sell fuel, automatically.
`vehicleClasses`	ARRAY	No	Filters results to specified vehicle classes. Each object must include `vehicleType` and `weightClass`. Example: `{ vehicleType: "Truck", weightClass: "Class8" }` If empty, all vehicle classes are included.
`vehicleClassSchemeId`	INTEGER	No	Vehicle classification scheme. Defaults to 2. Valid range: 0-5.
`vocations`	ARRAY	No	Filters results to specified vocation IDs. Retrieve valid vocation IDs from `GET /api/v2/filters/vocations` or the General API queryType: getVocations. If empty, all vocations are included.
`fleetSizeBins`	ARRAY	No	Defines fleet size bin upper bounds (ascending, inclusive). The lower bound of the first bin is 0; the upper bound of the last bin is unbounded. Applies to Geotab fleet devices only.

Primary response fields


Field	Type	Description
`inputId`	STRING	Encoded identifier for the anchor POI input.
`inputName`	STRING	Human-readable name of the anchor POI.
`inputType`	STRING	Type of the input zone (always "poi" for POI LSI queries).
`input_iso_3166_2`	STRING	ISO 3166-2 code for the anchor POI location.
`locationId`	STRING	Unique identifier for a POI location within the radius. One row per location in the response.
`locationName`	STRING	Descriptive name of the POI location described by this row.
`location_iso_3166_2`	STRING	ISO 3166-2 code for the POI location described by this row.
`locationNaics`	OBJECT	Category code and description for this POI location. Contains `code` and `description`.
`locationBrands`	ARRAY	Brand name or names associated with this POI location.
`locationLatitude`	FLOAT	Centroid latitude of this POI location.
`locationLongitude`	FLOAT	Centroid longitude of this POI location.
`locationIsOwned`	BOOLEAN	true if this location belongs to the same brand as the anchor POI.
`isOwned`	BOOLEAN	true if this location belongs to the same brand as the anchor POI.
`isSourceLocation`	BOOLEAN	true if this row represents the anchor POI itself rather than a competitor.
`competitorDensity`	INTEGER	Total number of competitor POI locations within the radius.
`stopCount`	INTEGER	Total stop events attributed to this location during the requested date range.
`tradeAreaStopCountTotal`	INTEGER	Total stop events across all locations within the radius. Divide a location's `stopCount` by this value to compute trade area stop share (market share proxy). See Reviewing POI LSI Results.
`stopDurationAvg`	FLOAT	Average stop duration at this location, in minutes.
`stopDurationMed`	FLOAT	Median stop duration at this location, in minutes.
`stopDurationStdev`	FLOAT	Standard deviation of stop duration at this location, in minutes.
`stopDurationBins`	ARRAY	Stop count by dwell-time bin. Six bins: (0-5], (5-15], (15-45], (45-120], (120-480], (480-inf] minutes. Each object contains `bin`, `lowerBound`, `upperBound`, and `stopCount`.
`stopCountByVehicleClass`	ARRAY	Stop count broken down by vehicle class. Each object contains `schemeId`, `categoryIndex`, `vehicleClassIndex`, `vehicleClass`, `vehicleClassId`, and `stopCount`. `vehicleClassId` is a stable identifier in the format `schemeId_categoryIndex_vehicleClassIndex` (for example, `2_2_0` = Heavy Duty under scheme 2). Use it to join vehicle-class breakdowns across endpoints.
`stopCountByVocation`	ARRAY	Stop count broken down by vocation. Each object contains `vocationId`, `vocation`, and `stopCount`.
`stopCountByFuelType`	ARRAY	Stop count broken down by fuel type. Fuel types: diesel, gasoline, electric, hybrid, flexible, other, unknown. Each object contains `fuelType` and `stopCount`.
`fleetSizeBins`	ARRAY	Stop count broken down by fleet size bin, as defined in the `fleetSizeBins` parameter. Applies to Geotab fleet devices only.
`displacement`	FLOAT	Straight-line distance from the anchor POI to this location, in miles.

Time series

When generateTimeSeries = true, a time series is generated in the background and retrieved separately from the GET /api/v2/poi/analytics/{id}/time-series endpoint. Time-series response fields:


Field	Type	Description
`aggregationUnit`	STRING	The aggregation granularity for this row: "month", "week", "dayofweek", or "hour".
`aggregationValue`	STRING	The specific period this row represents. For month: 1-12. For week: the start-of-week date. For dayofweek: 1-7 (Sunday = 1). For hour: 0-23.
`inputId`	STRING	ID of the anchor POI location for this row.
`inputName`	STRING	Name of the anchor POI location for this row.
`inputType`	STRING	Type of the input location. For POI queries, this is POI.
`input_iso_3166_2`	STRING	ISO 3166-2 code for the anchor POI location.
`locationId`	STRING	ID of the POI location described by this row. Join to the primary response on `locationId` for brand and location metadata.
`locationName`	STRING	Name of the POI location described by this row.
`location_iso_3166_2`	STRING	ISO 3166-2 code for the POI location described by this row.
`stopCount`	INTEGER	Stop events at this location for this aggregation period.
`stopDurationAvg`	FLOAT	Average stop duration for this aggregation period, in minutes.
`stopDurationMed`	FLOAT	Median stop duration for this aggregation period, in minutes.
`stopDurationBins`	ARRAY	Six-bin dwell distribution for this aggregation period (same bin structure as the primary response).
`stopCountByVehicleClass`	ARRAY	Vehicle class breakdown for this aggregation period.
`stopCountByVocation`	ARRAY	Vocation breakdown for this aggregation period.
`stopCountByFuelType`	ARRAY	Fuel type breakdown for this aggregation period.

Usage notes

Submit up to 20 location IDs per call (recommended ceiling; cost grows super-linearly above approximately 10 locations). For multi-site workflows, batch in groups of 20 or fewer and aggregate results client-side.
Use getPOISummary first to identify which competitor location IDs are present at your chosen radius before calling getPOIAnalytics.
tradeAreaStopCountTotal is always computed across the full radius regardless of any filtering applied via vehicleClasses, vocations, or fleetSizeBins. Use it as the denominator for trade area stop share.
Date ranges must align to full fiscal months (dateFrom = first of month, dateTo = last of month). Ranges between 1 and 12 months are supported.
Time series: the minimum viable window is 1 month; DayOfWeek is the recommended default (always 7 complete buckets); month and week are chronological, so data gaps appear as missing buckets, not nulls.

Note:

Each breakdown (vehicle class, vocation, and fuel type) includes a null or unknown bucket for stops where that attribute could not be classified. Breakdowns sum to stopCount only when the null bucket is included.

Note:

naics.code in the response may be 3 to 6 digits — the POI's own NAICS classification — and is not necessarily the Level-2 code you filtered on.

Note:

The radius is a straight-line distance and is not bounded by the discovery geography used in getPointsOfInterest. As a result, competitorDensity will not match the location count from the discovery step.

Note:

aggregationUnit values are lowercase in both requests and responses: month, week, dayofweek, hour.