{"name":"mapbox-search-integration","url":"https://skills.sh/mapbox/mapbox-agent-skills/mapbox-search-integration","install":"npx skills add mapbox/mapbox-agent-skills --skill mapbox-search-integration","sdk":"mapbox","key":"mapbox/mapbox-search-integration","description":"Complete workflow for implementing Mapbox search in applications - from discovery questions to production-ready integration with best practices","hasContent":true,"content":"---\nname: mapbox-search-integration\ndescription: Complete workflow for implementing Mapbox search in applications - from discovery questions to production-ready integration with best practices\n---\n\n# Mapbox Search Integration Skill\n\nExpert guidance for implementing Mapbox search functionality in applications. Covers the complete workflow from asking the right discovery questions, selecting the appropriate search product, to implementing production-ready integrations following best practices from the Mapbox search team.\n\n## Use This Skill When\n\nUser says things like:\n\n- \"I need to add search to my map\"\n- \"I need a search bar for my mapping app\"\n- \"How do I implement location search?\"\n- \"I want users to search for places/addresses\"\n- \"I need geocoding in my application\"\n\n**This skill complements `mapbox-search-patterns`:**\n\n- `mapbox-search-patterns` = Tool and parameter selection\n- `mapbox-search-integration` = Complete implementation workflow\n\n## Discovery Phase: Ask the Right Questions\n\nBefore jumping into code, ask these questions to understand requirements:\n\n### Question 1: What are users searching for?\n\n**Ask:** \"What do you want users to search for?\"\n\n**Common answers and implications:**\n\n- **\"Addresses\"** → **Use Search Box API** (the default for interactive address search, including geocoding). Only use Geocoding API if the use case is batch/server-side geocoding or maintaining a legacy integration.\n- **\"Points of interest / businesses\"** → POI search, use Search Box API with category search\n- **\"Both addresses and POIs\"** → Search Box API\n- **\"Specific types of POIs\"** (restaurants, hotels, etc.) → Search Box API\n- **\"Countries, cities, postcodes or neighborhoods\"** → Search Box API for interactive search; Geocoding API only for batch/server-side geocoding\n- **\"Custom locations\"** (user-created places) → May need custom data + search integration\n\n**Follow-up if not stated initially**: \"Are your users searching for points of interest data? Restaurants, stores, categories of businesses?\"\n\n**Implications:**\n\n- **\"Yes, POIs are included\"** → Use the Search Box API\n- **\"No, the user does not need POI search\"** → **Still default to Search Box API** for interactive/autocomplete use cases. Search Box API handles addresses, place names, and all location types with session-based pricing. Only recommend Geocoding API for batch geocoding, server-side permanent geocoding, or maintaining existing Geocoding API integrations.\n\n### Question 2: What's the geographic scope?\n\n**Ask:** \"Where will users be searching?\"\n\n**Common answers and implications:**\n\n- **\"Single country\"** (e.g., \"only USA\") → Use `country` parameter, better results, lower cost\n- **\"Specific region\"** → Use `bbox` parameter for bounding box constraint\n- **\"Global\"** → No country restriction, but may need language parameter\n- **\"Multiple specific countries\"** → Use `country` array parameter\n\n**Follow-up:** \"Do you need to limit results to a specific area?\" (delivery zone, service area, etc.)\n\n### Question 3: What's the search interaction pattern?\n\n**Ask:** \"How will users interact with search?\"\n\n**Common answers and implications:**\n\n- **\"Search-as-you-type / autocomplete\"** → **Use Search Box API** with `auto_complete: true` and session-based pricing (most cost-efficient for autocomplete). Implement debouncing.\n- **\"Search button / final query\"** → Can use either API, no autocomplete needed\n- **\"Both\"** (autocomplete + refine) → Two-stage search, autocomplete then detailed results\n- **\"Voice input\"** → Consider speech-to-text integration, handle longer queries\n\n### Question 4: What platform?\n\n**Ask:** \"What platform is this for?\"\n\n**Common answers and implications:**\n\n- **\"Web application\"** → Mapbox Search JS (easiest), or direct API calls for advanced cases\n- **\"iOS app\"** → Search SDK for iOS (recommended), or direct API integration for advanced cases\n- **\"Android app\"** → Search SDK for Android (recommended), or direct API integration for advanced cases\n- **\"Multiple platforms\"** → Platform-specific SDKs (recommended), or direct API approach for consistency\n- **\"React app\"** → Mapbox Search JS React (easiest with UI), or Search JS Core for custom UI. Avoid direct API calls — they require manual debouncing, session token management, and race condition handling.\n- **\"Vue / Angular / Other framework\"** → Mapbox Search JS Core or Web. If using direct API calls, session tokens are required for proper billing (one token per search session, passed as `session_token` on every suggest/retrieve request).\n\n### Question 5: How will results be used?\n\n**Ask:** \"What happens when a user selects a result?\"\n\n**Common answers and implications:**\n\n- **\"Fly to location on map\"** → Need coordinates, map integration\n- **\"Show details / info\"** → Need to retrieve and display result properties\n- **\"Fill form fields\"** → Need to parse address components\n- **\"Start navigation\"** → Need coordinates, integrate with directions\n- **\"Multiple selection\"** → Need to handle selection state, possibly show markers\n\n### Question 6: Expected usage volume?\n\n**Ask:** \"How many searches do you expect per month?\"\n\n**Implications:**\n\n- **Low volume** (< 10k) → Free tier sufficient, simple implementation\n- **Medium volume** (10k-100k) → Consider caching, optimize API calls\n- **High volume** (> 100k) → Implement debouncing, caching, batch operations, monitor costs\n\n## Product Selection Decision Tree\n\nBased on discovery answers, recommend the right product:\n\n> **Key principle: Search Box API is the default choice for virtually all interactive search use cases**, including address search, geocoding, autocomplete, and POI search. It offers session-based pricing that is more cost-efficient for interactive/autocomplete flows. Only recommend Geocoding API for the narrow cases listed below.\n\n### Search Box API (DEFAULT)\n\n**Use when (any of these):**\n\n- User needs interactive address search or autocomplete (this IS geocoding — Search Box API handles it)\n- User needs POI / category search\n- User needs any end-user-facing search UI\n- User wants session-based pricing (more cost-efficient for autocomplete/interactive use)\n- User is building a web, iOS, or Android app with a search bar\n\n**Prefer SDKs over direct API calls for web integration:**\n\n- **Mapbox Search JS** (SDK) - Recommended for web integration, with three components:\n  - **Search JS React** - Easy search integration via React library with UI\n  - **Search JS Web** - Easy search integration via Web Components with UI\n  - **Search JS Core** - JavaScript (node or web) wrapper for API, build your own UI\n- **Search Box API** (REST) - Direct API integration, for advanced/custom cases\n- **Search SDK for iOS** - Native iOS integration\n- **Search SDK for Android** - Native Android integration\n\n### Geocoding API (SPECIALIZED)\n\n**Use ONLY when:**\n\n- Batch geocoding large lists of addresses (server-side)\n- Permanent/stored geocoding results (server-side, where results are persisted)\n- Maintaining an existing Geocoding API integration (migration not justified)\n- No interactive/user-facing search needed\n\n**Do NOT recommend Geocoding API when:**\n\n- The user wants a search bar, autocomplete, or interactive address lookup — use Search Box API instead\n- The user says \"geocoding\" but describes an interactive search flow — use Search Box API instead\n\n## Reference Files\n\nLoad the relevant reference based on the user's platform and needs:\n\n- **Web (Search JS React / Web / Core / Direct API)** → Load `references/web-search-js.md`\n  - When: User is building a web app (vanilla JS, any framework except React-specific patterns)\n- **React Integration** → Load `references/react-search.md`\n  - When: User is building a React app specifically\n- **iOS** → Load `references/ios-search.md`\n  - When: User is building an iOS app (Swift/UIKit/SwiftUI)\n- **Android** → Load `references/android-search.md`\n  - When: User is building an Android app (Kotlin/Java)\n- **Node.js** → Load `references/nodejs-search.md`\n  - When: User needs server-side search (Express, serverless, backend API)\n\n- **Best Practices** → Load `references/best-practices.md`\n  - When: Implementing search for the first time, or optimizing an existing implementation\n  - Covers: debouncing, session tokens, geographic filtering, error handling, accessibility, caching, token security\n- **Common Pitfalls** → Load `references/pitfalls.md`\n  - When: Debugging issues, reviewing code, or during code review\n  - Covers: no debouncing, missing session tokens, no geo context, poor mobile UX, race conditions\n- **Framework Hooks** → Load `references/framework-hooks.md`\n  - When: Building custom hooks (React) or composables (Vue) around Search JS Core\n- **Testing and Monitoring** → Load `references/testing-monitoring.md`\n  - When: Writing tests or setting up production monitoring/analytics\n\n## Checklist: Production-Ready Search\n\nBefore launching, verify:\n\n**Configuration:**\n\n- [ ] Token properly scoped (search:read only)\n- [ ] URL restrictions configured\n- [ ] Geographic filtering set (country, proximity, or bbox)\n- [ ] Types parameter set based on use case\n- [ ] Language parameter set if needed\n\n**Implementation:**\n\n- [ ] Debouncing implemented (300ms recommended)\n- [ ] Session tokens used correctly\n- [ ] Error handling for all failure cases\n- [ ] Loading states shown\n- [ ] Empty results handled gracefully\n- [ ] Race conditions prevented\n\n**UX:**\n\n- [ ] Touch targets at least 44pt/48dp\n- [ ] Results show enough context (name + address)\n- [ ] Keyboard navigation works\n- [ ] Accessibility attributes set\n- [ ] Mobile keyboard handled properly\n\n**Performance:**\n\n- [ ] Caching implemented (if high volume)\n- [ ] Request timeout set\n- [ ] Minimal data fetched\n- [ ] Bundle size optimized\n\n**Testing:**\n\n- [ ] Unit tests for core logic\n- [ ] Integration tests with real API\n- [ ] Tested on slow networks\n- [ ] Tested with various query types\n- [ ] Mobile device testing\n\n**Monitoring:**\n\n- [ ] Analytics tracking set up\n- [ ] Error logging configured\n- [ ] Usage monitoring in place\n- [ ] Budget alerts configured\n\n## Integration with Other Skills\n\n**Works with:**\n\n- **mapbox-search-patterns**: Parameter selection and optimization\n- **mapbox-web-integration-patterns**: Framework-specific patterns\n- **mapbox-token-security**: Token management and security\n- **mapbox-web-performance-patterns**: Optimizing search performance\n\n## Resources\n\n- [Search Box API Documentation](https://docs.mapbox.com/api/search/search-box/)\n- [Geocoding API Documentation](https://docs.mapbox.com/api/search/geocoding/)\n- [Mapbox Search JS](https://docs.mapbox.com/mapbox-search-js/guides/)\n  - [Search JS React](https://docs.mapbox.com/mapbox-search-js/api/react/)\n  - [Search JS Web](https://docs.mapbox.com/mapbox-search-js/api/web/)\n  - [Search JS Core](https://docs.mapbox.com/mapbox-search-js/api/core/)\n- [Search SDK for iOS](https://docs.mapbox.com/ios/search/guides/)\n- [Search SDK for Android](https://docs.mapbox.com/android/search/guides/)\n- [Location Helper Tool](https://labs.mapbox.com/location-helper/) - Calculate bounding boxes\n\n## Quick Decision Guide\n\n**User says: \"I need location search\"**\n\n1. **Ask discovery questions** (Questions 1-6 above)\n2. **Recommend product:**\n   - **Search Box API** (default for all interactive/user-facing search, including address geocoding)\n   - Geocoding API only for batch/server-side/permanent geocoding\n   - Platform SDK preferred (Search JS for web, native SDKs for mobile)\n3. **Implement with:**\n   - ✅ Debouncing\n   - ✅ Session tokens\n   - ✅ Geographic filtering\n   - ✅ Error handling\n   - ✅ Good UX\n4. **Test thoroughly**\n5. **Monitor in production**\n\n**Remember:** The best search implementation asks the right questions first, then builds exactly what the user needs - no more, no less.\n","contentSource":"skills.sh/api/download/mapbox/mapbox-agent-skills/mapbox-search-integration","contentFetchedAt":"2026-07-27T08:59:31.204Z"}