SiteZeus Help

Appearance

Using Site Sonar ​

See also (agent workflow): site-sonar.md covers the agent's brand-discovery prompts, tier gating, cached-read vs re-run heuristics, and saved-layer recolor flow.

Quick Answer ​

Site Sonar is the workspace tool for market planning and whitespace discovery. Use it to choose what to score candidates with (Zeustimate, a Scorecard, or Both), scope the scan to states or DMAs, pick your points of interest, run a candidate search, review the ranked results, and then either export the results or save them as a reusable layer. Site Sonar is available on every plan: Emerging accounts score candidates with a Scorecard, and Enterprise accounts can score with a Scorecard, a Zeustimate, or Both.

Where To Find Site Sonar ​

  1. Open a workspace panel
  2. Click the + button in the tab strip
  3. Add Site Sonar

You can also show or hide the Site Sonar map overlay later from the Layers tab.

Before You Run Site Sonar ​

The Site Sonar settings pane is organized into cards, in this order: Score with, Geography, Points of Interest, Design, and Filters. Your saved runs appear above them. Configure the cards you need, then start the run.

Score With ​

The Score with card picks the scoring channel Site Sonar computes for every candidate. The Zeustimate and Both options appear only when the project has a forecast model (an Enterprise feature); otherwise the card is locked to Scorecard.

  • Zeustimate — rank candidates by the project's predictive revenue model only.
  • Scorecard — rank candidates by a saved scorecard's composite index.
  • Both — compute both, then choose which one colors the map and orders results.

When Scorecard or Both is selected, a Scorecard picker appears; choose one from Select a scorecard. A scorecard is required before the run can start — until you pick one, Site Sonar shows Pick a scorecard to enable the run. and the Run/Apply button stays disabled. If the picker is empty, create a scorecard first (see Using Scorecards).

In Both mode a Color & rank by control lets you switch the map coloring and result order between Zeustimate and Scorecard without re-running.

Distance Filter ​

Use the Distance filter when you want to eliminate nearby duplicates from the results. Turn it on to enable spacing controls, or leave it off to skip deduplication entirely.

When the filter is on, choose a spacing mode:

Radius — excludes any candidate that falls within a straight-line radius of a higher-revenue survivor. Use the slider (0.25–10 mi) or type a value directly into the input box (up to 50 mi) to set the radius. Click Apply to run the filter.

Drive time — excludes any candidate that falls inside a higher-revenue survivor's drive-time isochrone. Choose a preset from the dropdown: 3, 5, 8, 10, 15, 20, or 30 minutes. Click Apply to run the filter. A progress bar appears while the filter runs and shows how many candidates were kept and knocked out. A "Don't refresh" notice is shown during drive-time runs because the result is not recoverable if you navigate away before it finishes.

Both modes share the Filter out sites near exclusion picker. Use it to pre-exclude candidates that fall inside the spacing zone of your project's own existing or proposed sites — for example, to avoid siting near your mature or in-development locations. The picker groups subtypes under Existing sites and Proposed sites and shows a count for each subtype. Fresh runs start with Mature, New, Closed Temp, and In Development checked by default; uncheck any you do not need.

Spacing mode, distance value, drive-time minutes, and exclusion picker state are all saved when you save a layer, and restored instantly when you reload it (no re-run required).

Points of Interest ​

Use the Points of Interest tree to choose the brands or categories that matter for your search.

  • Expand categories to browse the hierarchy
  • Search inside the tree when you know the brand or concept you want
  • Adjust the POI selection before running or re-running the workflow

The header shows a running Selected count and a hard Limit of 50,000 locations per run. Site Sonar enforces this cap to keep runs responsive and rendering smooth. If your selection exceeds the limit, prune the tree — either by narrowing brand picks or by deselecting whole categories — before clicking Run Site Sonar.

Canada projects: When your project is set to Canada, the POI tree populates from the Canadian brand catalog. You will see Canadian retailers, restaurants, and services instead of (or in addition to) US-only chains. The search and selection experience is identical regardless of country.

How To Run Site Sonar ​

  1. Configure your filters and POIs
  2. Click Run Site Sonar
  3. Watch the progress panel as batches complete and points load
  4. Review the results table when processing finishes

While a run is active you can click Cancel Run if you need to stop it.

All filters — including distance spacing and the scorecard — can be configured before the first run; Site Sonar applies everything in the right order automatically (the revenue forecast is computed before revenue-based filtering, spacing before scoring).

Geography ​

The Geography card (the second card, below Score with) scopes the whole scan to one or more states and/or DMAs (media markets). Its dropdowns read All states and All DMAs when nothing is selected; the DMA list has a search box. Candidate points are only generated inside the selected geography, and the POI tree's location counts — and therefore the 50,000-point budget — are measured inside it too. When a geography is selected, the card notes that "POI counts and the 50,000-point budget are scoped to this geography," with a Clear link to reset it. Scanning "big box + auto & gas in Florida" spends your full point budget in Florida, so you can select far more categories than a nationwide scan allows. Leave both lists empty to scan nationwide. Geography changes queue on Apply Changes like any other run input, and the selection is saved with your run layers.

After you change the configuration, the button becomes Apply Changes (N) — the number counts the pending changes (POI selection, site criteria, geography, scoring channels, distance spacing, exclusions, and — in Zeustimate-only mode — the legacy scorecard overlay), and the tooltip names them. One click applies them all in the right order: changes that need a fresh run trigger one, while spacing-only changes apply without re-running. The revenue filter and the score-index range slider stay live and never require an apply.

To start over, use the reset button at the bottom of the panel — labeled Clear settings normally, or Reset run when you have loaded a saved layer and made unsaved edits to it.

Reading the Progress Bar ​

The progress strip shows where the run is:

  • A phase label names the current stage: Queued..., Scoring, Loading results, Finalizing, Complete, or Run failed.
  • A ~N% complete readout and a bar track overall progress, with a sub-line reading <N> of <M> locations loaded as results stream onto the map.
  • Elapsed and estimated remaining times (m:ss elapsed, ~m:ss remaining) appear during longer runs.
  • The bar holds at Loading results until the map and table finish hydrating, so it does not report "complete" before the results are actually on screen.
  • The run identifier (saved-layer name) appears next to the status when you re-run an edited saved layer, so you can tell at a glance which run the bar is tracking.

The bar auto-hides shortly after a successful run; failures stay visible with the error message so you don't lose context.

Refresh resilience: if you refresh the browser while a run is in progress, the progress bar reappears and polling resumes automatically against the same job -- regardless of which tab is active when the page reloads. You do not need to open the Site Sonar tab first; the session restores from any workspace view. If the server can no longer find the original job (for example, after a long delay), a "could not be recovered" notice appears and the bar clears.

Designing How Results Render ​

The Design card appears once a run is on the map (or after you load a saved layer for editing). Use it to control how Site Sonar candidates draw:

  • Color scheme: new runs default to Classes (Natural Breaks) with five classes. Switch to gradient mode if you prefer a continuous scale.
  • Classified breaks: in Classes mode the initial breaks are computed from the run's data using Natural Breaks (Jenks). Edit any break boundary or switch the classification method (Equal Interval, Quantile, etc.) from the break editor. A count-weighted histogram shows the distribution across your classes.
  • Dot size: a px slider that scales the rendered marker size. The preference persists per browser so the look you set is restored on reload.

The Design card mirrors the dot-size and color controls used by Shapes and Listings, so a single visual language carries across map-rendered features.

Understanding The Results ​

The Site Sonar tab gives you two views at once:

  • A results table for sorting and reviewing candidate sites
  • A map overlay that uses the revenue legend colors shown at the top of the panel
  • A Saved Layers section for reloading previously saved Site Sonar result sets

Hover over any Site Sonar dot on the map to see a tooltip that includes the site's revenue grade (A-F). The grade shown in the tooltip is always the canonical grade from the project's mature-site percentile thresholds -- the same grade that appears in the results table for that site. This applies to both active-run dots and saved-layer dots.

If no run has completed yet, the table remains empty until Site Sonar returns results.

Filtering Results By Revenue ​

Revenue Filter ​

The Revenue filter limits results to a revenue band. Because the filter range is seeded from the current run's actual revenue distribution, the toggle is disabled until a run completes.

Custom metric label: If your project has renamed its sales metric (for example "Gallons" or "Visits"), the filter label changes to match. The behavior is identical — it still gates on the site's forecasted sales value, just shown under the configured name. See Configuring the Project Metric.

After a run finishes:

  • Turn it on to set a minimum and maximum range
  • Leave it off to include all values

Use it to narrow a large candidate set to a commercially viable band before exporting.

Which band filter you see depends on your scoring channel. In the Zeustimate channel you get the Revenue (or your project's custom metric) band. In the Scorecard channel the Revenue band is replaced by a score-index range slider. In Both, both sliders appear and apply together.

Scoring Site Sonar Results ​

The way candidates are scored and ranked is set by the Score with card at the top of the settings pane (see Score With), not by a toggle down in Filters:

  • Zeustimate ranks by predicted revenue alone.
  • Scorecard ranks by a saved scorecard's composite index. You must pick a scorecard before the run can start.
  • Both computes each candidate's Zeustimate and scorecard index; use Color & rank by to choose which one drives the map colors and result order.

Switching the scoring channel is a run-stage change: it queues on Apply Changes and triggers a re-run. Picking a scorecard (or changing which one) before the first run scores the candidates automatically once the run completes.

Min Index (Zeustimate-only legacy path). When Site Sonar is in the Zeustimate channel, the Filters card still offers the older Scorecard overlay with a Min Index slider (0.00–2.00) for a quick post-run index cutoff. This legacy overlay is hidden whenever the Scorecard or Both channel is active — in those modes, use the Score with card and the score-index range slider instead.

Exporting And Saving Results ​

Use the Export / Save menu in the results area when you want to take Site Sonar results out of the app.

Available actions:

  • Export to CSV
  • Save as Layer

Export to CSV ​

Use this when you want a portable file for downstream review and sharing. The exported file includes each result's Latitude and Longitude columns (alongside its name and scores), so you can map or geocode the sites in another tool without looking coordinates up separately.

Save as Layer ​

Use this when you want to keep the current Site Sonar result set inside Zeus.ai:

  1. Open Export / Save
  2. Click Save as Layer
  3. Enter a name for the layer
  4. Click Save Layer

After the save completes:

  • the result set is stored for the current project
  • it appears in the Saved Layers section of the Site Sonar tab
  • you can load it later without re-running Site Sonar first

Large runs (tens of thousands of locations) may take several seconds to save. While a save is in progress, a loading overlay covers the Site Sonar tab and shows a contextual label — Saving view..., Saving changes..., or Renaming... depending on the operation. Interactions with the tab are blocked during the save to prevent accidental duplicate submissions. The overlay disappears automatically when the operation finishes.

Loading And Comparing Saved Layers ​

The Saved Layers section shows the Site Sonar layers already saved for the current project.

Use it when you want to:

  • return to a previous Site Sonar run
  • compare multiple saved candidate sets side-by-side on the map
  • restore Sonar results after switching focus to other work

Site Sonar separates two independent states for each saved layer:

  • Visibility — whether the layer is rendered on the map. Controlled by the eye icon on each row.
  • Editing focus — which layer's results populate the results table and receive Design card changes. Controlled by clicking the row body. The focused row shows an Editing pill.

Only one layer can have editing focus at a time. Up to five layers can be visible at once.

Showing and Hiding Layers on the Map ​

Click the eye icon on a saved-layer row to toggle that layer's map visibility on or off. This does not change which layer has editing focus. You can independently show or hide as many layers as you like (up to five at once), regardless of which one you are editing.

Activating a sixth layer is blocked until you hide one of the visible five.

Setting Editing Focus ​

Click anywhere on a saved-layer row body (not the eye icon) to make that layer the editing target. Its results populate the results table, and Design card changes apply to it. The row shows an Editing pill and receives a highlighted border while it has focus.

Loading a layer for editing automatically shows it on the map if it was not already visible.

Clicking a row that already has editing focus is a no-op. To remove editing focus from a layer, hide it using the eye icon.

Switching Between Saved Layers ​

When multiple saved layers are loaded, you can work with them independently:

  • Eye icon: show or hide a layer on the map without changing which layer is the editing target
  • Row body click: move editing focus to a different layer (results table and Design card follow)
  • Rename / Delete: housekeeping actions available from the row menu

A footer line at the bottom of the list reads Visible: N of M · Editing: name so you can tell at a glance what is rendered and what is being edited.

How Site Sonar Fits With The Map ​

The Site Sonar layer can be shown or hidden from the Layers tab.

That is useful when you want to:

  • Compare Site Sonar candidates with your existing and proposed sites
  • Pair Site Sonar results with traffic or transit overlays
  • Clean up the map while you focus on table review

The Layers tab shows an Editing badge next to whichever saved run currently has editing focus in the Site Sonar tab. This lets you check which run the editor panel is bound to without switching tabs.

Capturing Site Sonar in a Map Report ​

Site Sonar has a Map report button (camera icon) in its tab header, tooltip "Create a map report of the visible Site Sonar runs." Click it to freeze the runs currently on the map into an interactive, shareable Map Report locked to the Site Sonar layer. This now includes a freshly-run, unsaved run — you no longer have to save a layer first for it to show on the map legend or be captured in a report. See Map Reports for how Map Reports are viewed and shared.

Including Saved Runs on Report Maps ​

Any saved Site Sonar run can also be overlaid on a frozen analytics report map from the report builder. That selection is independent of the live workspace map -- you explicitly choose which runs to bake into each report, regardless of what is currently visible on the map.

How to add saved runs to a report map ​

  1. Open the Map card settings (gear icon on the Map card in the report builder, or expand the Map section in the Location Analytics tab placeholder).
  2. In the Datasets section, toggle on Site Sonar.
  3. A Sonar runs sub-section appears listing the project's saved Site Sonar layers. Check the runs you want to include.
  4. Select up to 5 runs. Further checkboxes disable once the cap is reached.
  5. Run the report. The forecast dots for the selected runs are cropped to the subject window and baked into the frozen map.

What recipients see ​

  • Interactive web viewer: the selected runs' forecast dots render live on the frozen map, colored by each run's Zeustimate revenue scale.
  • PDF and deck exports: the dots are rasterized at capture time and appear on the static map image.
  • Legend: one colored row per included run -- the run's name and its accent color -- matching the legend style on the live workspace map.

Notes ​

  • If no saved runs exist in the project, the sub-section shows a notice instead of checkboxes. Save a run first (see Exporting And Saving Results), then return to the map settings.
  • Runs are picked by their saved name. If you rename or delete a run after configuring the report, the row stays visible and clearable in the settings until you remove it.
  • The selection does not affect which runs are visible on the live workspace map.

Tips ​

  • Start with a smaller POI selection when you are testing a new market.
  • Use the Zeustimate channel for a fast first pass, then switch the Score with card to Scorecard or Both when you want criteria-based ranking.
  • Use the score-index range slider (or Min Index in the Zeustimate channel) to narrow the list without losing the full run.
  • Use Apply Changes whenever you adjust the scoring channel, POI mix, geography, or distance spacing — the badge tells you how many changes are queued, and only the stages that need to re-run do.
  • Save high-value runs as layers so you can reload them later during planning sessions; the distance filter mode, value, and exclusion picker selection are all saved with the layer.
  • Use the eye icon to show multiple saved runs on the map at the same time; click the row body to move editing focus to the run you want to adjust.
  • For the Revenue filter (labeled with your project's metric name if configured), the toggle is grayed out until a run completes — run Site Sonar first, then enable the filter.
  • Prefer Radius mode for quick passes on small projects; use Drive time mode when you need realistic trade-area spacing and have a project with pre-cached isochrones.

Troubleshooting ​

I do not see results yet ​

Wait for the progress panel to finish. Site Sonar loads results as batches complete.

I refreshed the browser during a run ​

The run restores automatically regardless of which tab is open when the page reloads. The progress bar reappears and polling resumes against the same job. If the job can no longer be found on the server, you will see a "could not be recovered" notice -- start a new run in that case.

The Revenue filter toggle is grayed out ​

The filter requires a completed run to seed its value range. Run Site Sonar first, then enable the toggle. (If your project uses a custom metric name, the filter label reflects that name, but the toggle behavior is the same.)

The scorecard selector is empty ​

Create a scorecard first in the Scorecards tab (add it from the + menu in the tab strip, or ask Zeus.ai chat to open it), then return to Site Sonar.

I selected too many POIs to run ​

Site Sonar caps each run at 50,000 locations. Look at the Selected / Limit counter in the POI tree header. If you're over the cap, deselect a category or narrow the brand selection until you're back inside the limit.

I can't see all my saved layers on the map ​

You can show up to five saved layers at once. Hide one to make room for the next.

The map is too busy ​

Open the Layers tab and temporarily hide other layers while you review Site Sonar results.

I clicked a saved layer that was already selected and nothing happened ​

Clicking the row body of the layer that already has editing focus is intentional — it is a no-op. To remove it from the map, click its eye icon instead. Eye-off on the editing layer hides it and clears editing focus at the same time.

I cannot find my saved layer ​

Refresh the Saved Layers section and confirm you are still in the same project where the layer was saved.

The Distance filter is on but candidates still appear too close together ​

The filter does not apply automatically — you need to click Apply after setting the radius or drive-time value. If you already clicked Apply but the map looks unfiltered, check whether the mode toggle is set to the mode you intended (Radius vs Drive time) and click Apply again.

Drive-time spacing is taking a long time ​

A drive-time spacing pass on a 50,000-candidate run can take several minutes. Do not refresh the browser while the progress bar is active — the result would be lost and you would need to click Apply again. Once the run completes, saving the layer persists the survivor set so future reloads are instant.

I see a "Filter quality reduced" warning after applying drive-time spacing ​

This warning appears when the isochrone cache did not have pre-computed drive-time polygons for some of the surviving sites. Those sites contributed no exclusion zone, which means some nearby candidates may have survived that would otherwise have been knocked out. The cache is pre-warmed by the platform automatically; try clicking Apply again after a few minutes if you see this warning.

What the AI can do for you with this ​

Zeus.ai Chat can run, monitor, render, re-rank, and revisit Site Sonar without ever leaving the chat thread. Capabilities (catalog names):

  • Run Site Sonar (runSiteSonar) — kick off a fresh Site Sonar batch run, including the brand-discovery step the agent uses to resolve ambiguous brand names before launching.
  • Check Sonar Status (getSonarStatus) — poll the progress of an in-flight run. For large brand sets (15+ batches), a run can take several minutes; the agent keeps polling until completed or failed rather than giving up after a few checks.
  • Site Sonar Results (getSonarResults) — fetch the most recent Site Sonar run for a project, including the ranked candidate list.
  • Show Sonar Results on Map (showSonarResultsOnMap) — render a completed agent-driven run on the map. Agent sonar runs execute server-side and do not automatically draw on the map; after the run finishes, the agent calls this to load the ranked dots and turn the Site Sonar layer on. Ask "Run Site Sonar for Chipotle and show me the results on the map" and the agent will handle both steps.
  • Scorecard Evaluation (evaluateScorecard) — apply a saved scorecard to the current Sonar result set so the candidates rank by composite index rather than revenue alone.
  • Map & App Control (mapControl) — focus the Site Sonar tab, toggle the Sonar overlay on/off, or jump to a specific candidate on the map.
  • Reports, Views, History & Help Docs (generateReport) — package the ranked candidate list into a deliverable deck or PDF.

Worked example ​

"Run Site Sonar for coffee brands and show me the results on the map."

The agent searches for matching POI brand triplets, then calls runSiteSonar. While the run is in progress it keeps polling getSonarStatus until the job reaches completed -- for large brand sets this can take several minutes, and the agent reports batch progress (N of M batches) rather than treating a running status as a failure. Once complete, the agent calls showSonarResultsOnMap so the ranked dots appear on the map. Repeated status questions during the run use the cached job state rather than spawning a duplicate run.

SiteZeus Location Intelligence Platform — powered by Zeus.ai

© 2026 SiteZeus. All rights reserved.