Atlases

Atlases overview

An Atlas is a collection of locations: your stores, branches, dealers, service points, or territories. An Atlas works the way a dataset does, but for places instead of people — where a dataset has identity columns and traits per person, an Atlas has placement columns and properties per location.

Atlases can help you:

• Send each customer to the location that's actually closest to them, instead of guessing from ZIP code or region.
• Build a population from a radius around one location, a group of locations, or every location you operate.
• Reach people who have just moved into the area around a location — or who have moved out of one (requires mover data).
• Compare who lives near your locations against who actually buys from you, so you can see which groups you've already saturated and which you haven't.
• Find the markets you don't cover by inverting that radius.
• Report on real distance, in a real unit, rather than a set of fixed yes/no distance flags.

Once an Atlas is built, its locations can be used in two places: as a spatial filter on a cohort, and as location data in a deployment payload. A market opportunity analysis can also be scoped to an Atlas footprint.

Anatomy of an Atlas

Every Atlas needs a name, connection options, and a location schema. The schema (output_to_locations in the API) maps columns in your source data onto each location.

Reference keys and properties are what make one Atlas flexible enough to answer many questions. With them, a single Atlas covering your whole network can answer a question about one region, one store format, or any subset — you don't need a separate Atlas per question.

Placing your locations

Each location is placed by exactly one of three column groups. Mixing groups is rejected.

Coordinates are more accurate than addresses. Geocoding re-derives a position you already know, usually landing 10–100 meters off, and it can fail on individual rows without any obvious signal in your output. If your export contains coordinates in any form, use them — including when they arrive combined in a single column, which you can split into two numeric columns before upload.

A geometry column can hold a point, a line, or an area — all are valid, so use this option whenever that's how your locations are stored, whatever their shape. An area is used in full: distance is measured to its nearest edge, not its center.

Creating an Atlas

In the dashboard, create an Atlas from a hosted CSV or an existing connection, then map your placement columns, the name, the reference key, and any properties.

Through the API, start with a CSV of your locations — one row per location, with latitude and longitude columns if you have them. Upload the file:

curl --request POST \
  --url https://api.faraday.ai/v1/uploads/locations/YOUR_CSV_FILE.csv \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $FARADAY_API_KEY' \
  --data-binary @YOUR_CSV_FILE.csv

Then create the Atlas with a POST /atlases request:

curl https://api.faraday.ai/atlases --json '{
  "name": "Store locations",
  "options": {
    "type": "hosted_csv",
    "upload_directory": "locations"
  },
  "output_to_locations": {
    "name": "store_name",
    "latitude": "latitude",
    "longitude": "longitude",
    "reference_key": "store_id",
    "properties": [
      { "name": "store_status", "column": "store_status" }
    ]
  }
}'

Your Atlas builds in the background. To check on it, use a GET /atlases request:

[{
  "name": "Store locations",
  "id": "$STORE_LOCATIONS_ATLAS_ID",
  "status": "ready",
  "counts": {
    "rows": 120,
    "locatable": 120
, ...}
, ...}]

Make note of the ID — you'll need it to attach location data to a deployment.

Checking a build

After an Atlas builds, compare the number of source rows against the number of locations that were successfully placed. These should match. A shortfall means some rows couldn't be placed, so those locations won't exist in the Atlas at all — nobody will be routed to them, and no radius around them will return anyone. Worth investigating before you build anything on top of the Atlas.

Filtering a cohort by proximity

A cohort can filter its membership by proximity to an Atlas's locations. You control three things:

• Distance. Set in miles. Everyone within that many miles of a location matches.
• Which locations. By default, every location in the Atlas is included. You can narrow it — see Narrowing the match, further down this page.
• Inside or outside. The default selects people inside the radius. Inverting it selects everyone outside, which is how you find markets you don't currently cover.

Combining proximity with everything else

A location condition is one condition among many. Proximity narrows a cohort geographically; the events and traits in the same cohort definition narrow it by behavior and characteristics. Together they answer questions neither could alone:

• People who recently moved in near a location — a radius around your locations, plus a recent move.
• Nearby people who aren't customers yet — a radius around your locations, with your customers excluded.
• Nearby people who match your best customers — a radius around your locations, plus the traits that distinguish who already buys from you.

The third is worth dwelling on. A cohort of everyone living near your locations, compared against your actual customer base, shows you which groups in your catchment you've already reached and which you haven't — the difference between a market that's saturated and one that's untapped.

For how to combine conditions in a cohort, see Cohorts.

How to attach Nearest Location to a deployment

Nearest Location is a payload option rather than a resource of its own: any deployment can carry each person's closest location and the distance to it, alongside whatever predictions it already delivers. Turn it on in the pipeline's payload and point it at an Atlas.

You get three columns per person:

Turning on Nearest Location

In the pipeline's Payload, tick Indicate the nearest location to each person. That alone is enough — every location in the account is matched, and the nearest one wins.

Advanced settings holds the rest:

• Atlases — restrict matching to the Atlases you name. Leave it empty to use every Atlas in the account.
• Location properties — narrow which locations each person is matched against.
• Output — report the nearest location for each row, or list every location meeting your conditions.
• Maximum distance (miles) — optional for the nearest location, required when listing all of them.

Through the API, the same configuration is the location member of a pipeline's payload:

curl https://api.faraday.ai/scopes --json '{
  "name": "Nearest Location",
  "population": {
    "include": [
      "$CUSTOMERS_COHORT_ID"
    ]
  },
  "payload": {
    "location": {
      "select": "nearest",
      "conditions": {
        "atlas_ids": [
          "$STORE_LOCATIONS_ATLAS_ID"
        ]
      }
    }
  }
}'

The population is a cohort — usually your customer list. If you don't have one yet, build it first in Cohorts, then reference its ID here. Once the pipeline runs, the three location columns are delivered wherever that pipeline already sends data; see Deployments to add a destination.

Where Faraday doesn't hold a residence for a person, all three columns come back empty rather than being filled with an arbitrary location.

Assigning only to certain locations

If your Atlas covers more locations than you want to assign against — planned locations, a different banner, a region you're not mailing — filter them with property conditions. Only matching locations are considered.

curl https://api.faraday.ai/scopes --json '{
  "name": "Nearest open location",
  "population": {
    "include": [
      "$CUSTOMERS_COHORT_ID"
    ]
  },
  "payload": {
    "location": {
      "select": "nearest",
      "conditions": {
        "atlas_ids": [
          "$STORE_LOCATIONS_ATLAS_ID"
        ],
        "property_conditions": [
          {
            "property": "store_status",
            "_eq": "Active"
          }
        ]
      }
    }
  }
}'

You can also bound the assignment with max_distance, in meters. A person outside that bound is assigned nothing, which is usually what you want when a store 400 miles away isn't a real option.

Nearest location only, or all eligible locations

An Atlas can return either one location per person or several. Which you choose changes the shape of all three columns.

Because the distance column changes type between the two modes, any deployment already delivering these columns has to be rebuilt after you switch. Ideally, decide which mode you want before you wire up delivery.

Narrowing the match

Whether you're filtering a cohort or attaching location data to a deployment, the same three filters control which of an Atlas's locations a person is matched against.

A fourth filter, location_reference_keys, matches only the locations carrying the reference keys you name. It is set through the API rather than the dashboard, and a configuration set that way survives an edit made in the dashboard. Reference keys are unique within a single Atlas only. When you filter by key across several Atlases, the keys are matched in each one — so name a single Atlas when filtering by key.

Things worth knowing

Distance is geometric, not drive time. Distances are straight-line, measured to the nearest edge of a location. There's no drive-time option today.

Some people won't get a location. Assignment depends on Faraday holding a residence for a person. Where we don't, all three location columns come back empty rather than being filled with an arbitrary location — a wrong location is worse than none. So fewer people will carry location data than are in the deployment. How many depends on your list.

Rebuilds are triggered by change, not by a schedule. An Atlas rebuilds when its configuration changes or when Faraday detects new or changed location data at the source — adding locations, removing them, or editing existing ones. There's no fixed interval, so there's no window in which your Atlas is knowingly stale. To replace an uploaded file, upload the new version to the same directory.

Deleting or archiving an Atlas

Before deleting an Atlas, make sure no cohort, deployment, or market opportunity analysis is still using it.

• Dashboard: click the ... menu on the Atlas you'd like to delete or archive, then choose the relevant option.
• API: use the delete Atlas or archive Atlas requests.

Common questions about Atlases

What's the difference between an Atlas and a place?

A place is a single area or address set you define by hand in the dashboard. An Atlas holds many locations imported from your own source data, and each location carries a name, a reference key, and properties you can filter on. Places still work, but Atlases supersede them, and a single cohort can't use both place conditions and location conditions.

How does Faraday decide which location is closest to a person?

Faraday measures straight-line distance from the residence it holds for a person to the nearest edge of each location's geometry, then returns the closest match. Distance is geometric, not drive time.

Why do some people have no location data?

Location assignment depends on Faraday holding a residence for that person. Where there isn't one, all three location columns come back empty rather than being filled with an arbitrary location.

Should I place locations by coordinates or by address?

Use coordinates when you have them. Faraday can geocode street addresses during the build, but geocoding re-derives a position you already know and can fail on individual rows without an obvious signal in your output.

Can one Atlas cover locations that need different treatment?

Yes. Give each location a reference key and any properties that distinguish it — region, format, open or planned — then filter on those wherever the Atlas is used. One Atlas covering your whole network can answer questions about any subset of it.

What unit are distances reported in?

Meters. The dashboard accepts distances in miles when you set a radius or a maximum distance, but output values are always in meters. One mile is 1,609 meters.

Can I combine proximity with other conditions?

Yes. A location condition sits alongside the events and traits in a cohort definition, so you can define a group like "people within 10 miles of a location who recently moved" or "people near a location who aren't customers yet." See Cohorts for how conditions combine.

How often does an Atlas rebuild?

There's no schedule. An Atlas rebuilds when its configuration changes or when Faraday detects a change to the location data at its source, the same way a dataset rebuilds when new data is pushed to it.