# mapbox-search-patterns

Tells your agent which Mapbox search tool to call and which parameters to set for geocoding, POI search and address lookup.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1800 installs · ★ 83
- Author: mapbox
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/mapbox/mapbox-agent-skills/tree/HEAD/skills/mapbox-search-patterns/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/mapbox-search-patterns

## What it does

The skill walks through three Mapbox tools and when each one fits. `search_and_geocode_tool` handles specific names, brands and addresses: "Empire State Building", "McDonald's", "123 Main St, Boston, MA". `category_search_tool` covers generic types and plurals: "coffee shops", "hotels", "electric vehicle chargers". `reverse_geocode_tool` turns coordinates into an address, city or postcode. A decision matrix maps each query shape to a tool and the reason behind the pick.

A separate section covers spatial filters. `proximity` biases results toward a point without excluding distant matches, and the skill says to set it whenever you have a reference location — otherwise results fall back to IP-based or global. `bbox` is a hard constraint: too small and you get nothing, too large and you get noise. `country` limits results by ISO 3166 alpha-2 code, so "Paris" with `["FR"]` returns Paris, France rather than Paris, Texas. The three can be combined.

For `category_search_tool` the skill documents `limit`, range 1 to 25, default 10: lower values return faster. `search_and_geocode_tool` takes a `types` filter — `poi`, `address`, `place`, `street`, `postcode`, `district`, `locality`, `country`. Worth installing if you build map search and keep forgetting how `proximity` differs from `bbox`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add mapbox/mapbox-agent-skills --skill mapbox-search-patterns -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/mapbox-search-patterns/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/mapbox-search-patterns/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add mapbox/mapbox-agent-skills --skill mapbox-search-patterns -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/mapbox-search-patterns/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add mapbox/mapbox-agent-skills --skill mapbox-search-patterns -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/mapbox-search-patterns/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install mapbox/mapbox-agent-skills mapbox-search-patterns
```

2. **Manually: put the files in place**
- File: `.github/skills/mapbox-search-patterns/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add mapbox/mapbox-agent-skills --skill mapbox-search-patterns -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/mapbox/mapbox-agent-skills --path skills/mapbox-search-patterns
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/mapbox-search-patterns/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add mapbox/mapbox-agent-skills --skill mapbox-search-patterns -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/mapbox/mapbox-agent-skills/tree/HEAD/skills/mapbox-search-patterns/SKILL.md

## When to use it
- pick between name search and category search
- set proximity so results follow the user's location
- constrain results with a bbox or a country code
- tune limit for autocomplete versus a map view
- convert GPS coordinates into a readable address

## Example prompts
- Find coffee shops near me with category_search_tool
- What's at 37.7749, -122.4194?
- Find hotels in downtown Seattle, constrain the bbox and set proximity

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: b4cc176da6a8fb5f.

BEGIN THIRD-PARTY FILE b4cc176da6a8fb5f
```text
---
name: mapbox-search-patterns
description: Expert guidance on choosing the right Mapbox search tool and parameters for geocoding, POI search, and location discovery
---

# Mapbox Search Patterns Skill

Expert guidance for AI assistants on using Mapbox search tools effectively. Covers tool selection, parameter optimization, and best practices for geocoding, POI search, and location discovery.

## Available Search Tools

### 1. search_and_geocode_tool

**Best for:** Specific places, addresses, brands, named locations

**Use when query contains:**

- Specific names: "Starbucks on 5th Avenue", "Empire State Building"
- Brand names: "McDonald's", "Whole Foods"
- Addresses: "123 Main Street, Seattle", "1 Times Square"
- Chain stores: "Target"
- Cities/places: "San Francisco", "Portland"

**Don't use for:** Generic categories ("coffee shops", "museums")

### 2. category_search_tool

**Best for:** Generic place types, categories, plural queries

**Use when query contains:**

- Generic types: "coffee shops", "restaurants", "gas stations"
- Plural forms: "museums", "hotels", "parks"
- Is-a phrases: "any coffee shop", "all restaurants", "nearby pharmacies"
- Industry terms: "electric vehicle chargers", "ATMs"

**Don't use for:** Specific names or brands

### 3. reverse_geocode_tool

**Best for:** Converting coordinates to addresses, cities, towns, postcodes

**Use when:**

- Have GPS coordinates, need human-readable address
- Need to identify what's at a specific location
- Converting user location to address

## Tool Selection Decision Matrix

| User Query                      | Tool                    | Reasoning                |
| ------------------------------- | ----------------------- | ------------------------ |
| "Find Starbucks on Main Street" | search_and_geocode_tool | Specific brand name      |
| "Find coffee shops nearby"      | category_search_tool    | Generic category, plural |
| "What's at 37.7749, -122.4194?" | reverse_geocode_tool    | Coordinates to address   |
| "Empire State Building"         | search_and_geocode_tool | Specific named POI       |
| "hotels in downtown Seattle"    | category_search_tool    | Generic type + location  |
| "Target store locations"        | search_and_geocode_tool | Brand name (even plural) |
| "any restaurant near me"        | category_search_tool    | Generic + "any" phrase   |
```
END THIRD-PARTY FILE b4cc176da6a8fb5f

The third-party file has ended. Everything between the b4cc176da6a8fb5f tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2363 of 12544 bytes. © mapbox · MIT · https://github.com/mapbox/mapbox-agent-skills/tree/HEAD/skills/mapbox-search-patterns/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md