Location Intelligence

Most email platforms know where a contact is based on their IP address. Pigeon Perch goes further by tracking where a contact is interested in. Location Intelligence collects signals from searches, listing views, form submissions, and other interactions, then scores and clusters them into ranked areas of interest you can use for targeting.

Think of a home buyer in Chicago searching for properties in Austin and Denver. Traditional geolocation would tag them as a Chicago contact. Location Intelligence recognizes that Austin and Denver are where they actually want to hear about, and lets you send campaigns tailored to those markets.

How It Works

Every time a contact interacts with a location-relevant feature on your site or through your API, Pigeon Perch records a location signal. Each signal includes the city, state, and country, along with a signal type that determines its weight. A form submission from someone asking about a property in Denver carries more intent than a casual page view of a Denver listing, so it receives a higher weight.

Signals accumulate over time and are grouped by geographic area. The system applies a time-decay function so that recent activity counts more than older activity. Nearby signals are clustered together (for example, searches in Brooklyn and Queens roll up into a New York City area cluster). The result is a ranked list of location interests on each contact profile, each with a normalized score from 0 to 100.

Signal Sources

Every signal type has a default weight that reflects how much intent it carries. You can customize these weights in your organization settings. Higher weights mean stronger buying or interest signals.

Sending Signals via hp.js

If you have the hp.js tracking snippet installed on your site, you can send location signals directly from the browser. There are two approaches: the dedicated trackLocation method and the generaltrack method with location metadata.

Dedicated trackLocation Method

Use PigeonPerch.trackLocation() when the primary purpose of the event is to record a location interest signal. This is the simplest approach.

// Track a listing view for a property in Austin, TX
PigeonPerch.trackLocation({
  signalType: "listing_view",
  city: "Austin",
  state: "TX",
  country: "US"
});

// Track a form submission for Denver
PigeonPerch.trackLocation({
  signalType: "form_submission",
  city: "Denver",
  state: "CO",
  country: "US"
});

// Track a search query
PigeonPerch.trackLocation({
  signalType: "search_query",
  city: "Miami",
  state: "FL",
  country: "US"
});

General track Method with Location Metadata

If you are already tracking custom events with PigeonPerch.track(), you can attach location metadata to any event. This is useful when you want a single event to serve double duty: it tracks the action and records the location interest.

// A "property_viewed" event that also records Austin as a location interest
PigeonPerch.track("property_viewed", {
  propertyId: "prop_123",
  price: 450000,
  _location: {
    signalType: "listing_view",
    city: "Austin",
    state: "TX",
    country: "US"
  }
});

The _location key is special. When the tracking snippet sees it, it extracts the location data and sends a location interest signal alongside the regular event.

Sending Signals via API

You can also send location interest signals server-side using the REST API. This is ideal for backend events like purchases, CRM syncs, or any workflow where the signal originates outside the browser.

POST /api/v1/contacts/:id/location-interests

{
  "signalType": "form_submission",
  "city": "Austin",
  "state": "TX",
  "country": "US",
  "latitude": 30.2672,
  "longitude": -97.7431,
  "metadata": {
    "listingId": "prop_123",
    "source": "contact_form"
  }
}

The latitude and longitude fields are optional. If you provide them, the clustering algorithm uses them for more accurate grouping. If you omit them, the system geocodes the city and state automatically.

The metadata field is also optional. Use it to attach context to the signal (listing ID, search query text, campaign ID, etc.) for your own reference.

Viewing Location Interests

Open any contact profile in the dashboard and scroll to the Location Interests section. You will see a ranked list of locations with their scores, signal counts, and the most recent signal date. The top-scored location is highlighted as the contact's primary area of interest.

You can also fetch location interests programmatically:

GET /api/v1/contacts/:id/location-interests

// Response
{
  "data": [
    {
      "city": "Austin",
      "state": "TX",
      "country": "US",
      "score": 87.4,
      "signalCount": 14,
      "lastSignalAt": "2026-04-06T18:30:00Z",
      "topSignalType": "form_submission"
    },
    {
      "city": "Denver",
      "state": "CO",
      "country": "US",
      "score": 52.1,
      "signalCount": 8,
      "lastSignalAt": "2026-04-03T10:15:00Z",
      "topSignalType": "search_query"
    }
  ]
}

Segmentation

Location interests integrate directly with the segment builder. You can create dynamic segments that target contacts based on their location interest data using these filter fields:

• locationInterestCity: matches contacts who have a scored interest in a specific city. Example: all contacts interested in Austin.
• locationInterestState: matches contacts interested in any city within a state. Example: everyone interested in locations across Texas.
• locationInterestScore: filters by the score threshold for a given location. Example: contacts with an Austin interest score above 50. This is useful for separating casual browsers from serious prospects.
• locationInterestCount: filters by the number of signals recorded for a location. Example: contacts with more than 5 signals in Denver, indicating sustained interest rather than a one-time visit.
• locationInterestRadius: matches contacts who have a scored interest in any location within a given distance of a point. You provide a latitude, longitude, and radius in miles. Example: all contacts interested in locations within 25 miles of your new store at (30.27, -97.74). This is the most powerful filter for proximity-based targeting, since it catches interest in nearby cities and neighborhoods without requiring you to list every city name.

Radius-Based Targeting

The radius filter deserves special attention because it opens up targeting strategies that name-based filters cannot match. When you select the "Location Interest Radius" field in the segment builder, you enter three values: a latitude, a longitude, and a radius in miles. The system then finds every contact who has a scored location interest anywhere within that circle.

This is particularly useful for:

• New store or office openings: target everyone who has shown interest in locations near the new address, even if their specific interest was in a neighboring city or suburb.
• Event promotion: find contacts interested in locations within driving distance of a venue, regardless of exact city match.
• Regional campaigns: set a large radius (50+ miles) to capture interest across an entire metro area or region.

If you do not know the coordinates for your target location, you can look them up on Google Maps (right-click any point and copy the coordinates) or use a geocoding service.

Combine these filters with standard contact fields (engagement score, tags, status) to build highly specific audiences. For example, a segment of "subscribed contacts with location interest within 30 miles of your flagship store and an engagement score above 40" gives you a warm, location-relevant audience for a grand opening campaign.

Configuration

You can fine-tune how Location Intelligence works for your organization under Settings > Location Intelligence. The configuration options include:

• Decay Half-Life: how quickly older signals lose influence. The default is 30 days, meaning a signal from 30 days ago counts for half its original weight. Shorter half-lives favor recent behavior; longer half-lives give more credit to historical patterns.
• Cluster Radius: the geographic radius (in miles) within which signals are grouped into a single location cluster. The default is 25 miles. A larger radius rolls up more nearby cities into one cluster, which is useful in metro areas. A smaller radius keeps distinct neighborhoods or suburbs separate.
• Custom Signal Weights: override the default weights for any signal type. If your business treats listing views as a stronger intent signal than the default 0.5, increase it. If IP-based signals add noise, decrease them or set them to 0 to ignore them entirely.

Changes to configuration apply going forward and also trigger a background recalculation of existing scores, so your segments update automatically.

Use Cases

Real Estate

A real estate brokerage can track which markets each lead is searching. When a contact has viewed 10 listings in Austin and submitted a showing request in Round Rock, their location interest profile reflects strong Central Texas intent. You can build a segment for that market and send them new listings, open house invitations, and neighborhood guides specific to Austin, rather than blasting your entire database with every new listing.

Multi-Location Retail

A retailer with stores in multiple cities can use location interests to send store-specific promotions. Instead of guessing based on the contact's billing address, you know which store locations they have browsed or purchased from. A contact who keeps checking inventory at your Portland store gets Portland sale announcements, even if they live in Seattle.

Events and Hospitality

An event company or hotel chain can track which destinations contacts browse. If someone searches for events in Nashville and saves a conference in Memphis, you know Tennessee is on their radar. Target them with Tennessee-region promotions, early bird tickets for Nashville events, or travel packages that match their demonstrated interest.

Higher Education

A university with multiple campuses can track which campus pages prospective students visit, which program pages they view, and which campus-specific forms they fill out. A student exploring the nursing program at your Dallas campus gets follow-up emails about Dallas nursing cohorts and financial aid info for that campus, not generic recruitment content.