mapbox_autocomplete_place_search 1.0.0

A Flutter package for Mapbox place search with autocomplete functionality, featuring flexible JSON parsing, comprehensive error handling, and easy-to-use widgets for place search and selection.

Mapbox Autocomplete Place Search

A Flutter package for Mapbox place search with autocomplete functionality, featuring flexible JSON parsing, comprehensive error handling, and easy-to-use widgets for place search and selection.

Features

✨ Easy-to-use widgets - Drop-in place search fields and dialogs
🔍 Autocomplete search - Real-time search suggestions as you type
🌍 Flexible filtering - Filter by place types, countries, and proximity
🛡️ Robust error handling - Comprehensive error handling and logging
📱 Mobile optimized - Built specifically for Flutter mobile apps
🔧 Customizable - Extensive configuration options for different use cases

Getting started

Prerequisites

1. Mapbox Account: Sign up at Mapbox to get an access token
2. Flutter SDK: Ensure you have Flutter 3.0.0 or higher installed

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  mapbox_autocomplete_place_search: ^1.0.0

Setup

1. Get your Mapbox access token from Mapbox Account
2. Use a PUBLIC token (pk.) - not a secret key (sk.) for client-side operations
3. Configure your token in your app

Usage

Basic Place Search Field

import 'package:mapbox_autocomplete_place_search/mapbox_autocomplete_place_search.dart';

PlaceSearchField(
  accessToken: 'your_mapbox_access_token_here',
  hintText: 'Search for a place...',
  maxResults: 5,
  onPlaceSelected: (place) {
    print('Selected: ${place.text} at ${place.latitude}, ${place.longitude}');
  },
)

Place Search Dialog

showDialog(
  context: context,
  builder: (context) => PlaceSearchDialog(
    accessToken: 'your_mapbox_access_token_here',
    title: 'Search for Places',
    hintText: 'Enter place name...',
    onPlaceSelected: (place) {
      print('Selected: ${place.text}');
      Navigator.of(context).pop();
    },
  ),
);

Advanced Search with Filtering

final geocodingService = MapboxGeocodingService(
  accessToken: 'your_mapbox_access_token_here',
);

final results = await geocodingService.searchPlaces(
  query: 'New York',
  limit: 10,
  types: ['place', 'locality', 'neighborhood'],
  country: ['us'],
  proximity: [-74.006, 40.7128], // NYC coordinates
);

Available Place Types

• country - Countries
• region - States/provinces
• postcode - ZIP codes
• district - Districts
• place - Cities/towns
• locality - Localities
• neighborhood - Neighborhoods
• address - Street addresses
• poi - Points of interest

API Reference

PlaceSearchField

A text field with built-in autocomplete place search.

Properties:

• accessToken - Your Mapbox access token (required)
• hintText - Placeholder text for the search field
• maxResults - Maximum number of search results to show
• onPlaceSelected - Callback when a place is selected

PlaceSearchDialog

A full-screen dialog for place search.

Properties:

• accessToken - Your Mapbox access token (required)
• title - Dialog title
• hintText - Placeholder text for the search field
• onPlaceSelected - Callback when a place is selected

MapboxGeocodingService

Direct API service for custom implementations.

Methods:

• searchPlaces() - Search for places by query
• reverseGeocode() - Get place details from coordinates
• getPlaceDetails() - Get details for a specific place ID

Place Model

Represents a place returned from the API.

Properties:

• id - Unique identifier
• text - Display text
• placeName - Full place name
• latitude / longitude - Coordinates
• placeType - Type of place
• relevance - Search relevance score

Error Handling

The package includes comprehensive error handling:

• API Errors: Proper HTTP status code handling
• Parsing Errors: Robust JSON parsing with fallbacks
• Network Errors: Graceful handling of connection issues
• Debug Logging: Extensive logging for troubleshooting

Debug Logging

Enable detailed logging to troubleshoot issues:

// Console output shows:
// 🔍 Starting place search
// 📡 API request details
// ✅ Response received
// 📍 Results found
// ❌ Any errors that occur

Example

See the /example folder for a complete working example with multiple search implementations.

Additional information

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Issues

If you encounter any issues, please file them at the GitHub repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Dependencies

• http - For API calls to Mapbox
• json_annotation - For JSON serialization
• json_serializable - For code generation

Mapbox API

This package uses the Mapbox Geocoding API. Please refer to their documentation for API limits and usage guidelines.