# Map

> See where your clocked-in team members are on a live map, follow the path a worker took during a work session, and filter by project, status or name.

Source: https://docs.cooperbuild.ai/connect/map
Last updated: 2026-10-05
Keywords: team map, team location map, gps, gps tracking, live location, field staff location, crew tracking, where is my crew, work sessions, check-in location, geolocation, location pings

The Map shows where your team members are while they are on the clock. Every pin on the map is a **work session**: when a worker checks in, Cooper records where they checked in, and while the session runs their phone keeps sending location updates. The map moves as those updates arrive.

Office admins, project managers and supervisors use the Map to see who is on which job site right now, check that a crew has arrived, and look back at the route a worker took during a session.

![The Team Location Map with a team member pin on the map and the Team Members list on the right](https://docs.cooperbuild.ai/screenshots/connect/map-overview.png)

*Screenshot: The Map. 1: filters, 2: map style, 3: a team member pin, 4: Team Members list, 5: quick filter cards.*

## Key concepts

| Term | Meaning |
|---|---|
| **Work session** | One shift for one team member, from check-in to check-out. The Map shows one entry per work session, so a person with two sessions in the time window can appear twice. |
| **Location ping** | A location update sent by the worker's phone while their work session is in progress. Each ping has a time, coordinates, and (when the phone reports them) accuracy and battery level. |
| **Last seen** | The time of the newest location Cooper has for the session: the latest ping, or the check-out or check-in location if there are no pings. |
| **Activity** | Where the last-seen location came from: **Ping** (a live update), **Checkout** or **Checkin**. |
| **Active** | A team member whose last-seen location is from the past hour. |
| **Session status** | The work session's status: **In Progress**, **Completed**, **Approved**, **Flagged**, **In Timesheet** or **Paid**. |

## Open the Map

In the sidebar, open **Connect** and click **Map**. The page opens at `/connect/team-member-map` with the title **Team Location Map**.

You see the Map only if your role grants **Map** under **Connect** (read access). Account owners always see it. If your company's plan does not include the Map, you see a locked screen instead.

## What the Map shows by default

When you open the Map with no filters, it shows:

- every work session that is **In Progress**, and
- every work session that was **Completed** in the past 24 hours.

Sessions are sorted newest first and loaded 50 at a time. The page reloads its data every 30 seconds. Live location pings from workers' phones move the pins between reloads, without a refresh.

The header shows the state of the data at a glance:

| Badge | Meaning |
|---|---|
| **N active** | How many team members have a location from the past hour. |
| **N total** | How many work sessions match the current filters. |
| **LIVE** | Data loaded. |
| **NO DATA** | No work sessions match the current filters. |
| **N Live Updates** | How many sessions have sent a live location ping since you opened the page. This badge pulses. |

## Read a team member's pin

Each pin is a round avatar with the team member's first name underneath. The avatar is the person's profile photo, or a person icon when they have no photo.

- A **pulsing green ring** means the last location came from a live location ping.
- A **gray ring** means the last location came from the check-in or check-out, not from a live ping.

When nothing is selected, the map zooms and centers itself to fit every pin. Use the controls at the top left of the map to show your own location, go full screen, and zoom or rotate.

Sessions with no location at all (for example, a check-in made without GPS) do not get a pin. They still appear in the Team Members list with the note **No location data available**.

## Follow a team member's path

### Step 1: Select the team member
Click their pin on the map, or click their card in the **Team Members** list. The selected pin grows and the card is highlighted.

### Step 2: Read the path
The map draws a line through every location ping in that work session, oldest to newest:
- a large **green** dot marks where the journey started,
- small **blue** dots mark each location ping,
- a **red** dot marks the latest location.

The line is green when the latest ping is less than an hour old (the worker is being tracked live), and blue otherwise.

### Step 3: Inspect a point
Hover over any dot to see **Journey Start**, **Current Location** or **Location Ping #n**, with the team member's name and email, the project, the time of the ping and its accuracy (for example **Accuracy: ±12m**). A dot from a session that is being tracked live also shows **Live Tracking**.

A path appears only for sessions that have location pings. A session with only a check-in location shows a pin but no line.

## Read the Team Members list

The **Team Members** panel to the right of the map lists every work session that matches your filters. Each card shows:

| Field | What it means |
|---|---|
| Name and email | The team member. A small green dot on the avatar means they are active (seen in the past hour). |
| Status badge | The session status, for example **in progress** or **flagged**. |
| **Project** | The project the session is checked in to, or **N/A**. |
| **Check-in** | When the session started, shown as **Just now**, minutes or hours ago, or a date. |
| **Duration** | How long the session has run, for example **3h 15m**. Shown when Cooper has a duration. |
| **Activity** | **Ping**, **Checkout** or **Checkin** — where the last location came from. |
| **Last seen** | When the newest location was recorded. Not shown for sessions without location. |
| **Battery** | The phone's battery level, shown in green, amber or red. Shown when the phone reports it. |
| Address | The address recorded with the location, when there is one. |

Click **Refresh** at the top of the list to reload now instead of waiting for the next 30-second reload.

When more than 50 sessions match, the list shows **Showing X of Y (page a/b)**. Use the arrow buttons at the top or bottom of the list to move between pages. The map shows the pins for the page you are on.

## Filter the Map

Use the filter row above the map. Filters combine, and changing one returns you to page 1.

| Filter | What it does |
|---|---|
| **Search by name or email...** | Shows sessions for team members whose first name, last name, full name or email contains what you type. |
| **All Projects** | Pick one project to see only sessions checked in to it. Type to search projects. Clear the box to see all projects again. |
| **All Statuses** | Pick one status: **In Progress**, **Completed**, **Approved**, **Flagged**, **In Timesheet** or **Paid**. Clear the box to go back to the default view. |
| **Recent only** | Narrows the Team Members list to people whose last location is from the past hour. Pins on the map are not affected. |

> **Note: A status filter looks further back**
>
> With no status picked, the Map shows sessions in progress plus sessions completed in the past 24 hours. When you pick a status, the Map shows every work session with that status, however old. Combine a status with a project or a name to keep the list short.

## Use the quick filter cards

Below the map are four cards:

| Card | What it does |
|---|---|
| **All Sessions** | Clears every filter and shows the default view. Shows the total when no filter is on. |
| **In Progress** | Shows only sessions that are in progress. |
| **Completed** | Shows only completed sessions. |
| **Flagged** | Shows only flagged sessions. |

The selected card is highlighted and shows how many sessions match. Choosing **In Progress**, **Completed** or **Flagged** also turns off **Recent only**.

## Change the map style

Click **Day View**, **Night View** or **Satellite View** at the top right. The Map opens in **Day View** between 6 AM and 6 PM on your computer's clock, and in **Night View** otherwise. Your choice lasts until you leave the page.

![The Map in Satellite View with a team member pin over aerial imagery](https://docs.cooperbuild.ai/screenshots/connect/map-satellite.png)

*Screenshot: Satellite View helps you see exactly where on a site a worker is. 1: map style buttons, 2: map controls.*

## How locations are collected

Locations come from work sessions, not from tracking people all the time:

1. A team member checks in to a work session. Cooper records the check-in time and, when available, the location and device details.
2. While the session is in progress, the worker's phone sends location pings to Cooper. Cooper accepts a ping only for an in-progress session that belongs to the person sending it.
3. When the team member checks out, Cooper records the check-out location and stops accepting pings for that session.

No location is collected outside a work session. To see or edit the sessions themselves, open **Talent** → **Work Sessions**.

## Permissions

| What | Who can do it |
|---|---|
| Open the Map and see team member locations | Roles with **Connect** → **Map** (read). Account owners always. |
| Send location pings | The team member, from their own phone, during their own in-progress work session. |

The Map is read-only. Nothing on it changes a work session. To grant access, an admin opens **Settings** → **Roles**, edits the role, and turns on **Map** under **Connect**.

Live location updates are shared with everyone in your company who has the Map open. Grant the Map permission only to roles that need to see where people are.

## Tips and best practices

- Pick a project in **All Projects** to see who is on one job site.
- Turn on **Recent only** to hide people who checked in but have not sent a location in the past hour.
- Click a team member and look at the path to confirm a site visit, then check the hover times on the dots.
- Use **Flagged** to review sessions that need attention, then open them in **Work Sessions** to fix them.
- If a pin keeps a gray ring all day, the worker's phone is probably not sending location pings. Ask them to keep location turned on for the Cooper app while checked in.

## Troubleshooting

### I can't see Map in the sidebar

Your role does not include **Map** under **Connect**, or your company's plan does not include it. Ask an admin to turn on **Map** for your role in **Settings** → **Roles**.

### The header says NO DATA

No work session matches the current filters. Click **Clear Filters** in the Team Members list, or click the **All Sessions** card. With no filters, the Map shows only sessions in progress and sessions completed in the past 24 hours, so a day with no check-ins shows nothing.

### A team member is in the list but not on the map

Their work session has no location. The card says **No location data available**. This happens when the check-in was made without location and the phone has sent no pings. You can't select these cards.

### A pin isn't moving

The pin moves only when the worker's phone sends a location ping. If **Activity** says **Checkin** and the ring is gray, no pings have arrived for that session. Check that the worker is checked in on their phone, that location is allowed for the Cooper app, and that the phone has a data connection.

### I selected someone but no path appears

A path needs location pings. A session with only a check-in location shows a pin and no line.

### The list shows more people than the map

**Recent only** narrows the list but not the map, and sessions without a location appear only in the list. Also check the page number: the map shows the pins for the current page of 50 sessions.

### The map shows a 'Mapbox Map Not Available' message

The map service could not load in your browser. Cooper shows a simpler fallback map with the latest locations underneath the message. Refresh the page; if it keeps happening, report it to your admin.

## For AI agents

There is no MCP tool that returns live map coordinates or location pings. The Map is a screen for people.

To answer questions about who is or was clocked in, where they checked in, and their sessions, use the work-session tools:

| Tool | Use it for | Key parameters |
|---|---|---|
| `ws_browse` | List and search work sessions. Each session includes team member, project, check-in and check-out times, check-in method, address and battery level, duration, and status. | `teamMember` (name, email or Human ID), `project` (name or ID), `status` (`in_progress`, `completed`, `flagged`, `approved`, `in_timesheet`, `paid`, `excluded`), `dateFrom`, `dateTo` |

Common patterns:

- "Who is on site at Riverside right now?" → `ws_browse({ project: "Riverside", status: ["in_progress"] })`.
- "Where did Maria check in today?" → `ws_browse({ teamMember: "Maria", dateFrom: "<today>", dateTo: "<today>" })` and read the check-in address.

If the user wants to see the live position or the path a worker took, send them to **Connect** → **Map** (`/connect/team-member-map`) and tell them to click the person. The Map needs the **Connect** → **Map** permission; if the user can't see it, tell them to ask an admin to grant it.

## Related

- [Humans](https://docs.cooperbuild.ai/connect/humans.md) — the team members whose names and photos appear on the pins.
- [Teams](https://docs.cooperbuild.ai/connect/teams.md) — group the people you track.
- [Phone](https://docs.cooperbuild.ai/connect/phone.md) — call or text a team member you found on the map.