Developer API · v1
The Vantlens API: cited site-analysis reports, on demand.
The Vantlens API returns the same cited, synthesized site-analysis report sold as the $149 Location Report — demographics, trade areas, competition, daytime population, traffic, noise, housing, and brand fit, each field sourced to a named public dataset — as a metered, key-authenticated endpoint. It is self-serve from 25 free calls a month, with published per-call pricing instead of a sales contract.
Authentication is server-to-server Bearer auth. Email hello@vantlens.com for a key.
Quickstart
Submit, then poll
Report generation is asynchronous. A cold-area Overture parquet scan can take up to about 2 minutes, so POST returns 202 with a job ID instead of holding the connection open.
curl https://vantlens.com/api/v1/site-report \
-H "Authorization: Bearer $VANTLENS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: times-square-2026-07-18" \
-d '{"lat":40.758,"lng":-73.985,"radius_km":1,"name":"Times Square","brand":"Subway"}'curl https://vantlens.com/api/v1/site-report/jobs/5b1e...c2 \
-H "Authorization: Bearer $VANTLENS_API_KEY"Poll until status is done. Reuse an Idempotency-Key for safe retries within 24 hours.
Authentication
Bearer credentials stay on your server.
Send Authorization: Bearer <key> on POST and GET. Keys use the vlk_live_… or vlk_test_… format and are shown once. Email hello@vantlens.com for a key.
Request schema
| Field | Type | Rule |
|---|---|---|
| lat, lng | number | Required without polygon. Latitude −90–90; longitude −180–180. |
| radius_km | number | Radius trade area; defaults to 2 km and accepts values above 0 through 25. |
| drive_time_minutes | 5 | 10 | 15 | Drive-time trade area; mutually exclusive with radius and polygon. |
| drive_time_mode | auto | pedestrian | bicycle | Routing mode; defaults to auto and applies only to drive time. |
| polygon | GeoJSON | Polygon or MultiPolygon trade area; mutually exclusive with radius and drive time. |
| name | string | Optional report label, up to 80 characters; defaults to Site. |
| brand | string | Optional brand, up to 80 characters; adds brand fit and franchise system sections. |
Report fields
The report value is passed through from the report engine. Source and vintage details follow the public method register.
| Field | What it contains and cites |
|---|---|
| meta | Report label, coordinates, radius, generation time, country, and trade-area mode. |
| demographics | Population, households, income, age, rent, housing value, and tenure — ACS 2023 5-year or Statistics Canada 2021 Census. |
| tradeAreaPolygon | The computed 5/10/15-minute Valhalla isochrone or supplied GeoJSON boundary. |
| pois, density | Competitive mix, leading venues, and POIs per 1,000 residents — Overture Maps Places. |
| segments | Metro-relative neighbourhood archetype and segment shares from cited census inputs. |
| daytime | Jobs located in the trade area — US Census LEHD LODES. |
| benchmarks | Income, age, and rent indices against the county benchmark, where metro equals 100. |
| chains | Leading chains and independent-business share — Overture Maps Places. |
| voids | Regional chains present in the wider 20 km market but absent from the trade area. |
| livability | Reported-crime index and nearby schools — FBI, Statistics Canada, and NCES. |
| housing | Home value, owner share, and appreciation context — ACS/StatCan plus FHFA or NHPI. |
| noise | Measured US transportation-noise exposure or a labeled Canadian proxy, with cited NBER cost method. |
| flow | Modeled street traffic ranges and hourly curves, calibrated against 238 Toronto intersections. |
| disruption | Current work-zone exposure matched to the modeled street network. |
| transitAccess | Transit stops, parks, recreation, and parking — OpenStreetMap Overpass. |
| profileScores | Decision profiles with the factors that moved each score. |
| brandFit | Regional brand pattern and cannibalization context when brand is supplied. |
| sbaLoanPerformance | Franchise loan performance from the cited SBA 7(a)/504 ledger when available. |
| fddOutletHealth | Franchise system openings, closures, transfers, and state context from FDD Item 20. |
| sources_ok, sources_failed | The source register for this run. A source outage is disclosed instead of hidden. |
Graduated monthly pricing
| Calls per month | Price per call |
|---|---|
| 1–25 | $0.00 |
| 26–250 | $3.00 |
| 251–1,000 | $2.00 |
| 1,001–5,000 | $1.25 |
| 5,001+ | $0.75 |
At 100 calls, the first 25 are free and the next 75 cost $3 each: $225 for the month. At 1,000 calls, graduated pricing totals $2,175.
Placer.ai contracts are commonly sold as annual, sales-led subscriptions in the roughly $5,000–$50,000 range. Foursquare Places can price raw POI rows near $0.015 per call at volume. This API sits between them: a synthesized, cited trade-area report without an annual platform contract. Review the vendors’ current terms directly at Placer.ai and Foursquare Places.
Above 5,000 calls, email hello@vantlens.com to discuss a flat enterprise rate. Pricing will be revisited after the first 3–5 paying customers.
Errors
| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalid_lat_lng | Coordinates are missing or outside their valid ranges. |
| 400 | invalid_radius | radius_km is not above 0 and at most 25. |
| 400 | invalid_drive_time | Drive time or mode is unsupported. |
| 400 | invalid_polygon | The geometry is not a Polygon/MultiPolygon with coordinates. |
| 400 | conflicting_trade_area | More than one trade-area mode was supplied. |
| 400 | field_too_long | name or brand exceeds 80 characters. |
| 401 | invalid_api_key | The Bearer credential is missing, malformed, or unknown. |
| 403 | key_revoked | The credential has been revoked. |
| 404 | job_not_found | The job is unknown or belongs to another key. |
| 409 | idempotency_mismatch | The same idempotency key was used for a different body. |
| 429 | rate_limited | The key exceeded 10 submissions in one minute. |
| 500 | internal_error | The worker could not complete the report. |
Limits
25 free calls each month.
POST submissions are limited to 10 per minute per key. GET polling is unmetered and does not consume that submission limit.
Roadmap
POI churn is coming.
poi-churn will expose monthly openings, closures, and category shifts for watched metros. Ask if that feed belongs in your workflow.