> For the complete documentation index, see [llms.txt](https://docs.growthfactor.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.growthfactor.ai/study/pins.md).
# Pins
## What a Pin Can Represent
A pin marks a point on the study map. Use one for:
* A candidate site you're evaluating.
* A location you want data on — a pin can run **Site Score**, **Forecast**, **Cannibalization**, **Foot Traffic**, and **Vehicle Traffic**.
* An anchor for a trade zone. See [Shapes](/study/shapes.md).
***
## Dropping a Pin
Open the **Pins** group in the map toolbar, choose **Drop pin** (shortcut `D`), then click the map. You can also right-click any empty point on the map and choose **Drop pin here**. Drop a pin mode will stay on until you select a location to drop the pin or press `ESC`.
The pin that is created will be labelled with the street name from the address. The description will be the pin's full address.
### Searching for an Address
Choose **Search to drop pin** (shortcut `S`) to open a search box — **Search an address to drop a pin…**. Enter an address to drop a pin.
### Duplicate Pin Detection
If the point you click resolves to a place already pinned in the study, that existing pin is reused rather than a second one stacking on top of it.
When you ask the agent for an address instead, it checks for pins within 50 meters of that point first and asks whether you want to use the existing pin or drop a new one. The same check applies when it draws a trade zone at a raw coordinate.
***
## Naming a Pin
A pin's on-map label is its handle, and it's editable everywhere the pin appears: click the handle in the map toolbar or in the side panel header, or right-click the pin and choose **Rename**. Handles have to be unique within a study across pins and shapes alike, so a name already in use is rejected.
When you ask the agent to drop a pin you can give it a name up front, and that name becomes the label instead of the address.
***
## Moving a Pin
Select a pin, then drag it. Pins are only draggable while selected. Anything anchored to the pin, including its trade zones and any analysis run on it, refreshes at the new location. If a linked refresh doesn't finish, an error message appears notifying you to move the pin again to retry.
A pin linked to a deal can't be dragged — move the deal from its own detail page instead.
***
## The Pin Side Panel
Selecting a pin opens its detail panel on the right:
* **Name** — the pin's handle, editable in place, with its address beneath (coordinates when no address resolved).
* **Trade zones** — every zone anchored to this pin, plus a button to add another.
* **Data** — what's available for the location. See below.
* **Comments** — the pin's thread, with a count badge on the tab.
***
## Data at a Pin
The **Data** tab is where you see what's available for that location. Open one and it stays in the panel, so you can keep several in view at once.
* **Site Score** — a lens-weighted score for the location, broken out by lens. Admins get an **Edit** shortcut into the lens configuration. See [GrowthFactor Score](/data-and-analytics/growthfactor-score.md).
* **Forecast** — a sales projection from one of your workspace's predictive models. Pick the model and fill in its inputs, and you can inspect the analogs behind the result. See [Sales Forecast](/data-and-analytics/sales-forecast.md).
* **Cannibalization** — how much this pin's trade zone overlaps the other pins, stores, and deals in the study. See [Shapes](/study/shapes.md).
* **Foot Traffic** — visitation for the location.
* **Vehicle Traffic** — the nearest road's daily volume and hourly pattern. See [Vehicle Traffic](/data-and-analytics/vehicle-traffic.md).
Demographics is measured across an area, so it comes from a shape rather than a pin.
***
## Styling a Pin
Selecting a pin swaps the draw toolbar for a style toolbar with a **Pin color** swatch, **Draw trade zone**, and **Delete**. Color is the only visual property a pin has — fill and border styling apply to shapes.
***
## Commenting on a Pin
Open the **Comments** tab and type into **Add a comment to this pin…**, or right-click the pin and choose **Add comment**, which jumps straight to the tab with the box focused. Threads are flat — later entries post as replies into the same list under **Reply…**. See [Annotations and Comments](/study/annotations-and-comments.md).
***
## The Pin Context Menu
Right-click a pin for:
* **Draw trade zone**
* **Create deal** — hidden once the pin already has a linked deal
* **Add comment**
* **Rename**
* **Delete "P1"** — the item names the pin it will remove
***
## Existing Stores on the Map
### How Your Stores Appear
Your portfolio from [My Stores](/manage/my-stores.md) draws on the study map as the **All Stores** layer, clustered and toggleable like any other layer. Stores aren't part of the study document — every teammate with workspace access sees the same stores, and selecting one is a local action that changes nothing for anyone else.
### The Site Panel
Click a store to select it. The side panel opens on that store, headed by its site ID and address, and the map toolbar offers **Draw trade zone** — you can anchor a zone straight to the store without dropping a pin on top of it. The panel also lists **Trade zones** already anchored to the store and lets you run **Cannibalization** and **Vehicle Traffic** on it.
Right-clicking a store gives you just two items: **Draw trade zone** and **Update ID**. Stores have no comment threads.
### Editing Store Details
Edits in the panel write back to the store itself, so they show up everywhere that store appears:
* **Site ID** — the panel title; also reachable via **Update ID** on the context menu
* **Sales**
* **Sq ft**
* **Opened**
### Pins vs. Existing Stores
| Pin | Existing store |
| ---------------------------------------------- | ----------------------------------------- |
| A candidate location you place in a study | A location you already operate |
| Lives in the study | Lives in your workspace portfolio |
| Renameable, recolorable, deletable | Edit its ID, sales, sq ft, and open date |
| Has a comment thread | No comment thread |
| Its trade zones are deleted along with the pin | Its trade zones outlive any one study pin |
***
## Creating a Deal from a Pin
Click **Create deal** in the pin's side panel, or pick it from the pin's context menu. The deal is seeded from the pin — the handle becomes the title, the pin's address becomes the location, and any comments on the pin carry over as notes.
Creating the deal turns the pin itself into that deal on the map: it takes on its stage's color (it starts in the **Searched** stage) and shows a deal icon instead of its old styling, and it can no longer be dragged. Any trade zones anchored to the pin move over to the deal, so they stay linked. The pin also moves out of the **Pins** section and into **Deals & Stores** in the Study panel. See [Studies Overview](/study/overview.md).
Selecting it now opens the deal's detail view — showing both its site data and its deal fields — instead of the pin panel. A pin can only be linked to one deal, so once it's created, **Create deal** no longer appears on its context menu. See [Creating and Managing Deals](/deals/creating-and-managing-deals.md).
If the linked deal is later deleted, selecting the pin shows a notice that the deal is gone, with a **Delete pin** button to remove the orphaned pin and any of its trade zones.
{% hint style="info" %}
The deal is created in the study's workspace, which isn't always the workspace you have selected — a study shared with you from another workspace creates its deals there.
{% endhint %}
***
## Removing a Pin
Delete a pin from its context menu or the **Delete** button on the style toolbar. Deleting it also deletes any trade zone anchored to it. If the pin was created by an analysis, deleting it removes that whole analysis and everything else it produced.
Its comments go with it. Pinning the same spot again gives you a new pin, not the old one back.
***
## Asking the Agent
The agent can do all of the above. Try:
* "Drop a pin at 123 Main St and call it Site A"
* "Move P1 to 400 Oak Ave"
* "Make P1 orange"
* "What's the address of P2?"
* "Delete P3"
See [GrowthFactor Agent](/study/growthfactor-agent.md).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.growthfactor.ai/study/pins.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.