Skip to content

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.

InterfaceUse it whenAddress
MCP serverAn AI assistant such as Claude calls tools directly.https://app.lookalikeiq.com/mcp
REST APIA script or service sends HTTP requests.https://app.lookalikeiq.com/api/v1/
CLIA person or a shell-based agent works in a terminal.https://app.lookalikeiq.com/cli/lookalike.mjs

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.

  1. Sign in to LookAlike.
  2. Open Account from the user menu.
  3. Under API tokens, type a name and choose an expiry.
  4. Select Create token.
  5. 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.

ToolResult
list_brands, get_brandThe 99 curated brands, their store sources, footprint coherence, and typical store tract.
find_candidatesCensus 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_marketsMetro areas ranked by open high-resemblance tracts, median fit, or headroom.
evaluate_siteOne street address, ZIP code, city, or coordinate, scored and explained, with a 3, 5, and 10 km trade area.
describe_tractsUp to 10 tracts in one call, with every feature, national percentiles, and the brand’s typical range.
compare_brandsWhere two brands find the same or different neighborhoods.
map_previewA small PNG map of similarity, with numbered tracts, to show in a conversation.
search_metros, get_methodMetro codes, the model, thresholds, coverage, sources, caveats, and a glossary of every field.
make_map_link, save_viewLinks that open a specific map view.
list_views, rename_view, delete_viewSaved views from you and your organization.
get_accountYour 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.

Every tract result uses one format in every tool:

  • name, place, zip, county, and state say where the tract is. place is the Census place or town that contains the tract’s center. place_relation is near when the nearest place lies outside the tract, up to 25 km away.
  • similarity_percentile ranks the tract nationally. national_rank breaks ties; 1 is the most similar tract.
  • fit_band compares the tract with the brand’s own store tracts.
  • headline gives five standard values: income, education, density, home value, and age.
  • why and gaps list the features that raise and lower the score. within_brand_range is false when 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.
  • competitors counts competitor brands within 6 km. By default these are the other curated brands in the brand’s category. Set competitors or competitor_categories to choose others; a stores list has no default. interpreted.competitors lists the brands used.
  • nearby_chains counts 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.

Analysis tools accept these area filters:

FilterExample
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.

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.

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.

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_reliability set to true.
  • A factor has within_brand_range set 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.