Agent access overview
LookAlike has three interfaces for software agents. All three run the same analysis code as the map. All three return map links that open the matching view in a browser.
| Interface | Use it when | Address |
|---|---|---|
| MCP server | An AI assistant such as Claude calls tools directly. | https://app.lookalikeiq.com/mcp |
| REST API | A script or service sends HTTP requests. | https://app.lookalikeiq.com/api/v1/ |
| CLI | A person or a shell-based agent works in a terminal. | https://app.lookalikeiq.com/cli/lookalike.mjs |
Connect with sign-in
Section titled “Connect with sign-in”MCP clients that support OAuth, such as the Claude apps, connect by sign-in. Add https://app.lookalikeiq.com/mcp as a custom connector, sign in, and approve the app on the consent page. See MCP server. Account > Connected apps lists each approved app and disconnects it.
Create an API token
Section titled “Create an API token”- Sign in to LookAlike.
- Open Account from the user menu.
- Under API tokens, type a name and choose an expiry.
- Select Create token.
- Copy the token. LookAlike shows it once and stores only a hash.
A token starts with lk_. It acts as your account. It can run analyses, read saved views, and save, rename, or delete your own map views. It cannot change your workspace, datasets, billing, or team. LookAlike checks your account access on every request, so a revoked account stops all of its tokens at once.
Each account can hold 20 active tokens. Each account can make 1,200 agent requests per hour. Every response to a token request carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. get_account and GET /api/v1/me report the same usage.
What agents can do
Section titled “What agents can do”| Tool | Result |
|---|---|
list_brands, get_brand | The 99 curated brands, their store sources, footprint coherence, and typical store tract. |
find_candidates | Census tracts that resemble a brand’s store tracts, with place names, reasons, and gaps. It can save the top results as a map shortlist. |
rank_markets | Metro areas ranked by open high-resemblance tracts, median fit, or headroom. |
evaluate_site | One street address, ZIP code, city, or coordinate, scored and explained, with a 3, 5, and 10 km trade area. |
describe_tracts | Up to 10 tracts in one call, with every feature, national percentiles, and the brand’s typical range. |
compare_brands | Where two brands find the same or different neighborhoods. |
map_preview | A small PNG map of similarity, with numbered tracts, to show in a conversation. |
search_metros, get_method | Metro codes, the model, thresholds, coverage, sources, caveats, and a glossary of every field. |
make_map_link, save_view | Links that open a specific map view. |
list_views, rename_view, delete_view | Saved views from you and your organization. |
get_account | Your account, the active data release, and this hour’s usage. |
Every analysis tool accepts a curated brand or your own stores list. A brand id, a brand name, or the start of a name works, such as whole_foods, Whole Foods, or Sprouts. A stores list fits a new model to the tracts that hold those points. LookAlike saves the points once in a private view and reuses that view for the same list.
Read the results
Section titled “Read the results”Every tract result uses one format in every tool:
name,place,zip,county, andstatesay where the tract is.placeis the Census place or town that contains the tract’s center.place_relationisnearwhen the nearest place lies outside the tract, up to 25 km away.similarity_percentileranks the tract nationally.national_rankbreaks ties; 1 is the most similar tract.fit_bandcompares the tract with the brand’s own store tracts.headlinegives five standard values: income, education, density, home value, and age.whyandgapslist the features that raise and lower the score.within_brand_rangeisfalsewhen the value lies outside the middle 80 percent of the brand’s store tracts. Point these out, because they raise the score without resembling the stores.competitorscounts competitor brands within 6 km. By default these are the other curated brands in the brand’s category. Setcompetitorsorcompetitor_categoriesto choose others; a stores list has no default.interpreted.competitorslists the brands used.nearby_chainscounts every other curated brand within 6 km, in every category. It describes the retail setting, not competition.
Candidate lists state the headline labels and the brand’s typical values once, in headline_reference. Ask for detail: "brief" to list up to 100 candidates with only place, ZIP, similarity, rank, fit band, and link.
Each result also carries interpretation, one sentence to repeat to the user, and interpreted, which shows how LookAlike read each input. Check interpreted and warnings when a name could match more than one brand, metro, or county.
Call get_method, read the lookalike://glossary MCP resource, or call GET /api/v1/glossary for the meaning of every field.
Filter by area
Section titled “Filter by area”Analysis tools accept these area filters:
| Filter | Example |
|---|---|
state | "CO" or "CO, UT" |
exclude_states | ["TX"] |
counties | ["Alameda County, CA", "Contra Costa, CA"] |
metro | "Denver", 19740, or an alias such as "Bay Area" or "DFW" |
near | { "address": "Boise, ID", "radius_km": 20 } |
rank_markets also accepts min_market_tracts to leave out small metros. The map link shows one state, a metro, and the near point. interpreted.not_in_map_link lists any filter that the map cannot show.
Coverage
Section titled “Coverage”LookAlike covers census tracts in the 48 contiguous states and the District of Columbia. Alaska, Hawaii, Puerto Rico, and the other territories are not covered. Tools say so directly when a request names one of them.
Map links
Section titled “Map links”Every analysis result includes map_link fields. A map link opens LookAlike on the matching brand, report, metro, tract, and filters. Give the link to the user, or open it in the user’s browser. The user signs in to see the map. The sign-in page shows the link’s title, and the user returns to the view after sign-in.
Map links pin the national data release. A link therefore shows the same scores later. When a newer release exists, the map shows a notice with a Use current data button. See Map links and saved views.
How to present results
Section titled “How to present results”LookAlike describes resemblance. It shows where to look. It does not forecast sales, revenue, or foot traffic, and it does not decide whether to open a store.
Tell the user these facts when they apply:
- The brand’s footprint coherence is Moderate or Diffuse.
- A tract has
low_acs_reliabilityset to true. - A factor has
within_brand_rangeset to false. - A location was approximate, from a ZIP code or a city.
- A recommendation needs field checks of access, co-tenancy, real estate, and competition.