Radius Search — Setup Guide
Radius Search finds the contacts and companies in your HubSpot account that sit within a given distance of an address, and saves the results as a HubSpot list. This guide covers installing it, the one-time setup run, and running your first search.
Before you install
You need:
- A HubSpot account, on any tier. Radius Search works with Contacts and Companies, which every HubSpot account has.
- Permission to install apps in that account. In HubSpot this is normally a Super Admin, or a user with app install permissions.
- Address data in the standard HubSpot address properties. This is the one that matters, and it is the most common reason a first search returns nothing.
Radius Search builds each record's address from these four standard properties:
| HubSpot property | Internal name |
|---|---|
| Street Address | address |
| City | city |
| State/Region | state |
| Postal Code | zip |
A record does not need all four. A street address with a city and state works; so does a city and state on its own, or a postal code on its own — though the fewer parts are filled in, the less precisely the record can be placed. A record with none of them cannot be placed at all, and Radius Search will mark it as having no address rather than guessing.
If your addresses live in custom properties rather than the standard ones, copy them into the standard properties first. A HubSpot workflow or a quick import will do it.
Step 1 — Install the app
Install Radius Search from the HubSpot App Marketplace listing and choose the account you want to connect.
HubSpot will ask you to grant the app these permissions:
- Contacts — view and edit. To read each record's address and write its coordinates back.
- Companies — view and edit. The same, for companies.
- Contact and company properties — create. To create the Radius Search property group and its properties on first run. The app can create its own properties but cannot read your existing property settings, and it never alters properties it did not create.
- Lists — view and create. To save your search results as a list, and to find the lists it created earlier so it can update them.
The app requests nothing else. It cannot see your deals, tickets, emails, conversations, or anything else in your account.
On the first run the app creates a property group called Radius Search on contacts and companies. The properties in it are listed further down.
Step 2 — Open Radius Search
Radius Search runs as a full-page app inside HubSpot. There are two ways to open it, and either works.
From the Marketplace menu
- Click the Marketplace icon in the top navigation bar.
- In the dropdown, click View all.
- Choose Radius Search.
From your account settings
- Go to Settings.
- Open Connected Apps.
- Choose Radius Search.
Either route opens the Radius Search page, with two tabs — Search and Geocoding — and two links in the top right: Plan and billing, and Help. If you expect to use the app regularly, bookmark the page once it is open.
Step 3 — Run the first geocoding pass
Do this before your first search. A radius search compares coordinates, so your records need coordinates before there is anything to compare. Until a record has been through a geocoding run it will not appear in any search result.
- Open the Geocoding tab.
- Under Update coordinates, use Include to choose whether to process contacts, companies, or both.
- Start the run.
The run reads each record's address properties, works out the coordinates, and writes them back into that record's Radius Search properties. It works through your records in pages and reports progress as it goes. A large account takes a while; the run keeps its place, so progress is not lost if you navigate away.
When it finishes you will see Run complete with the counts for that run.
The Coverage table
Below the run controls, Coverage shows where your records stand, broken down by status. Use it to tell the difference between "the search found nothing" and "these records were never geocoded". If it reports that some records have never been processed, run the pass again with those object types included.
Coverage counts come from HubSpot's own property data, which takes a moment to index after a run. If the numbers look behind, the app will say that they are still catching up — wait a minute and reload rather than starting another run.
Step 4 — Run a search
Open the Search tab and fill in Search criteria:
| Field | What to enter |
|---|---|
| Record type | Contacts or Companies. One at a time. |
| Centre address | The point to search around — a street address, a city and state, or a ZIP code. |
| Radius | The distance to search. |
| Units | Miles or Kilometres. |
| Address confidence | How precisely a record's address must have matched to be included. See below. |
Address confidence
Not every address resolves equally well. A full street address usually lands on the building; a city and state lands on the middle of the city. Address confidence decides how much imprecision you are willing to include:
- Exact addresses only — only records that matched to a specific address. The tightest setting, and the right one when the distance really matters.
- Standard — the sensible default for most searches.
- Include uncertain matches — brings in records placed from partial addresses, such as a city or postal code alone.
- Include everything — every record with any coordinates at all, however roughly placed.
If a search returns fewer records than you expected, loosening this setting is the first thing to try.
Reading the results
Results show the number of Matches, and how many of them were placed from a Precise location versus an Approximate one, along with a table of the matching records and their addresses.
Two messages are worth knowing:
- Results were capped — the search hit its result limit. Narrow the radius or tighten the confidence setting to get a complete picture.
- Some addresses are incomplete — some records in range have partial address data, so their position is approximate. They are included, but treat the distance as a rough figure.
Step 5 — Save the results as a HubSpot list
Under Save as segment, choose what to do with the records you found:
- Create a new segment — makes a new HubSpot list from the results. Enter a Segment name, or leave it blank and the app will name it for you.
- Add to an existing segment — adds the results to a list the app created earlier, keeping what is already in it.
- Replace an existing segment — clears a list the app created earlier and fills it with the current results.
For the last two, use Find a segment to search by name, then pick the list under Segment to update.
Only lists created by Radius Search can be updated. HubSpot gives an app no reliable way to tell which lists came from where, so the app tracks the ones it made and offers only those. This is deliberate: it means Radius Search can never overwrite a list you built by hand.
The list it creates is an ordinary HubSpot list. Use it in workflows, views, emails, and reports like any other.
The properties Radius Search adds
All seven live in the Radius Search property group on contacts and companies. They are created on first run and populated by each geocoding pass.
| Property | Type | What it holds |
|---|---|---|
| Radius Search Latitude | Number | Latitude derived from this record's address. |
| Radius Search Longitude | Number | Longitude derived from this record's address. |
| Radius Search Geocode Status | Dropdown | Outcome of the most recent geocoding attempt — including that the record has no address to work from. |
| Radius Search Accuracy | Number | Geocoder confidence in the match, from 0 to 1. This is what the Address confidence setting filters on. |
| Radius Search Accuracy Type | Text | Precision of the match: rooftop, street_center, place and so on. A place-level match is a town centroid, not an address. |
| Radius Search Geocoded At | Date and time | When Radius Search last attempted this record, whether or not the attempt found a match. |
| Radius Search Address Hash | Text | A fingerprint of the address last geocoded, so unchanged addresses are not geocoded again. |
These are normal HubSpot properties. You can add them to views, filter on them, and report on them — filtering on Radius Search Geocode Status is a quick way to find records that need their addresses filled in. Editing them by hand is not recommended, as the next geocoding run will overwrite them.
Keeping coordinates current
Coordinates do not update themselves. When you add records, or change addresses on existing ones, run the geocoding pass again.
Re-running is cheap. The app compares each record's current address against the fingerprint it stored last time and skips any record whose address has not changed, so a second run only does the work that is actually new.
Plans and limits
Each plan includes a maximum number of geocoded records for the account. Plan and billing, in the top right of the app, shows your current plan and lets you change it. Plans and prices are listed at yellowlionapps.com.
If your account reaches its limit, further geocoding pauses until you move to a higher plan or the number of geocoded records falls back within it. Records already geocoded are never deleted because of a limit, and searching keeps working.
Troubleshooting
A search returns no matches. Work through these in order:
- Check the Coverage table on the Geocoding tab. If records have never been processed, run the geocoding pass — this is the usual cause of an empty first search.
- Loosen Address confidence. On the strictest setting, records placed from a city or ZIP alone are excluded.
- Widen the radius, and check the units are the ones you meant.
- Check the centre address resolves to where you think it does. Try a fuller version of it.
- Check that your records actually have address data in the four standard properties listed at the top of this guide.
Results were capped. The search reached its result limit, so what you are seeing is a subset. Narrow the radius or tighten the confidence setting.
Some addresses are incomplete. Records in range have only partial address data and are placed approximately. Filling in city, state, and postal code on those records and re-running the geocoding pass will place them properly.
Counts are still catching up. HubSpot takes a short time to index newly written properties. Wait a minute and reload; do not start a second run.
The run stopped, or could not start. Open the Geocoding tab and start it again — a run keeps its place, so it resumes rather than starting over. If it stops repeatedly, get in touch and include what the message said.
Could not create the segment. Usually a HubSpot lists permission or a list limit on the account. Confirm the installing user still has list permissions, then try again. The search results are not lost.
The app says it cannot update a list. Only lists Radius Search created can be updated. To take over a list you made by hand, create a new one from a search instead.
Uninstalling
Uninstall Radius Search from the connected apps section of your HubSpot account settings. That immediately revokes the app's access to your data.
What stays: the Radius Search properties and their values, and any lists the app created. They are yours, and it is up to you whether to keep or delete them.
If you are on a paid plan, cancel the subscription as well. Uninstalling the app stops its access to HubSpot, but it does not by itself cancel billing.
Getting help
Questions, problems, or anything this guide does not cover: yellowlionapps.com/support. Include your HubSpot account ID if you can — it lets us look at your install directly.
See also our Terms of Service and Privacy Policy. The Privacy Policy explains exactly what the app reads, what it stores, and what it does not.