# Agent access overview

How AI agents, scripts, and the command line use LookAlike without the map interface, and how they hand map views back to people.

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

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](https://docs.lookalikeiq.com/agents/mcp/). **Account > Connected apps** lists each approved app and disconnects it.

## Create an API token

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.

## 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

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.

## 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

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

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](https://docs.lookalikeiq.com/agents/map-links/).

## 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_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.

Canonical URL: https://docs.lookalikeiq.com/agents/overview/
