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:
curl -H "Authorization: Bearer lk_your_token" \ "https://app.lookalikeiq.com/api/v1/brands/trader_joes/candidates?state=CO&limit=5"Endpoints
Section titled “Endpoints”| Method and path | Tool |
|---|---|
GET /api/v1/me | Account, active release, usage, and endpoint addresses. |
GET /api/v1/glossary | The meaning of every result field. |
GET /api/v1/brands | list_brands |
GET /api/v1/brands/{brand} | get_brand |
GET /api/v1/brands/{brand}/candidates | find_candidates with query parameters |
GET /api/v1/brands/{brand}/markets | rank_markets with query parameters |
GET /api/v1/brands/{brand}/preview.png | map_preview as a PNG image |
POST /api/v1/candidates | find_candidates |
POST /api/v1/markets | rank_markets |
POST /api/v1/sites/evaluate | evaluate_site |
POST /api/v1/tracts | describe_tracts with geoids |
GET or POST /api/v1/tracts/{geoid} | describe_tracts for one tract |
POST /api/v1/compare | compare_brands |
POST /api/v1/preview | map_preview as JSON with a base64 image |
POST /api/v1/preview.png | map_preview as a PNG image |
GET /api/v1/metros?query= | search_metros |
GET /api/v1/method | get_method |
POST /api/v1/links | make_map_link |
POST /api/v1/links/saved | save_view |
GET /api/v1/views | list_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.
Score your own stores
Section titled “Score your own stores”Send a stores list instead of brand. Each store needs lat and lon. Send 3 to 5,000 stores.
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 and limits
Section titled “Errors and limits”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": "..." } }| Status | Meaning |
|---|---|
| 400 | The input is invalid. issues lists each problem and the valid choices. |
| 401 | The token is missing, wrong, expired, or revoked. |
| 403 | The account lost access, or the token called a route outside the agent API. |
| 404 | The saved view does not exist, or you did not create it. |
| 429 | The account made more than 1,200 agent requests in one hour. Retry-After gives the seconds to wait. |
| 502 | The address geocoder is unavailable. |
| 503 | The 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).