Skip to content

REST API

The REST API runs the same tools as the MCP server. The OpenAPI 3.1 document is at https://app.lookalikeiq.com/api/v1/openapi.json. It needs no token. Each response in it carries a schema with a description of every field.

Send the token in the Authorization header:

Terminal window
curl -H "Authorization: Bearer lk_your_token" \
"https://app.lookalikeiq.com/api/v1/brands/trader_joes/candidates?state=CO&limit=5"
Method and pathTool
GET /api/v1/meAccount, active release, usage, and endpoint addresses.
GET /api/v1/glossaryThe meaning of every result field.
GET /api/v1/brandslist_brands
GET /api/v1/brands/{brand}get_brand
GET /api/v1/brands/{brand}/candidatesfind_candidates with query parameters
GET /api/v1/brands/{brand}/marketsrank_markets with query parameters
GET /api/v1/brands/{brand}/preview.pngmap_preview as a PNG image
POST /api/v1/candidatesfind_candidates
POST /api/v1/marketsrank_markets
POST /api/v1/sites/evaluateevaluate_site
POST /api/v1/tractsdescribe_tracts with geoids
GET or POST /api/v1/tracts/{geoid}describe_tracts for one tract
POST /api/v1/comparecompare_brands
POST /api/v1/previewmap_preview as JSON with a base64 image
POST /api/v1/preview.pngmap_preview as a PNG image
GET /api/v1/metros?query=search_metros
GET /api/v1/methodget_method
POST /api/v1/linksmake_map_link
POST /api/v1/links/savedsave_view
GET /api/v1/viewslist_views
GET /api/v1/views/{id}Read a saved view.
PATCH /api/v1/views/{id}rename_view with { "title": "..." }
DELETE /api/v1/views/{id}delete_view

In query strings, write lists with commas, for example exclude_states=TX,OK. Write weight maps as key:value pairs, for example theme_weights=education:2,retail_dining_context:0. Send near and site in a POST body.

A PNG response carries the matching map link in the x-map-link header.

Send a stores list instead of brand. Each store needs lat and lon. Send 3 to 5,000 stores.

Terminal window
curl -X POST https://app.lookalikeiq.com/api/v1/candidates \
-H "Authorization: Bearer lk_your_token" -H "content-type: application/json" \
-d '{"stores":[{"lat":39.74,"lon":-104.99},{"lat":39.68,"lon":-104.94},{"lat":40.01,"lon":-105.27}],"stores_name":"Pilot","limit":5}'

LookAlike saves the store points once in a private view and reuses it for the same list. The map_link values open that view. Colleagues in your organization can open the links.

Errors use one shape:

{ "error": { "code": "INVALID_INPUT", "message": "input.limit must be at most 100", "issues": ["input.limit must be at most 100"], "requestId": "..." } }
StatusMeaning
400The input is invalid. issues lists each problem and the valid choices.
401The token is missing, wrong, expired, or revoked.
403The account lost access, or the token called a route outside the agent API.
404The saved view does not exist, or you did not create it.
429The account made more than 1,200 agent requests in one hour. Retry-After gives the seconds to wait.
502The address geocoder is unavailable.
503The national data release is unavailable.

Every response to a token request carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (seconds until the hourly window resets).