feat: Add example application for iOS, Android, and macOS, and introduce v6 API models. (#104)

Author: ketanchoyal

.github/workflows/dart.yml

@@ -11,9 +11,14 @@ jobs:
       - name: "Checkout"
         uses: actions/checkout@v2 # required!
 
+      - name: Create credentials.dart
+        run: |
+          rm -f test/credentials.dart
+          echo "const MAPBOX_KEY = '${{ secrets.MAPBOX_KEY }}';" > test/credentials.dart
+
       - name: ">> Flutter package <<"
         uses: k-paxian/dart-package-publisher@master
         with:
           credentialJson: ${{ secrets.CREDENTIAL_JSON }}
           flutter: true
-          skipTests: true
+          skipTests: false

.vscode/launch.json

@@ -0,0 +1,36 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "mapbox_search",
+            "request": "launch",
+            "type": "dart"
+        },
+        {
+            "name": "example",
+            "cwd": "example",
+            "program": "lib/main.dart",
+            "request": "launch",
+            "type": "dart"
+        },
+        {
+            "name": "example (profile mode)",
+            "cwd": "example",
+            "program": "lib/main.dart",
+            "request": "launch",
+            "type": "dart",
+            "flutterMode": "profile"
+        },
+        {
+            "name": "example (release mode)",
+            "cwd": "example",
+            "program": "lib/main.dart",
+            "request": "launch",
+            "type": "dart",
+            "flutterMode": "release"
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "dart.projectSearchDepth": 5
+}

CHANGELOG.md

@@ -1,3 +1,11 @@
+# [4.4.0] - 30 Dec 2025
+- Added Batch Geocoding support (v6) with `batch()` method.
+- Improved Static Image API:
+    - Fixed URL encoding for polylines.
+    - Added `auto` parameter for automatic viewport adjustment.
+    - Added `center` parameter requirement check for manual framing.
+- Enhanced Example App with tabs for Geocoding, Batch, and Static Images.
+
 # [4.3.2] - 11 Aug 2025
 - Fixed Typecasting issue in `BBox` (Fix #100)
 

README.md

@@ -107,61 +107,83 @@ Future<ApiResponse<List<MapBoxPlace>>> getPlaces() =>
     );
 ```
 
+### Batch Geocoding (v6)
+Perform multiple geocoding queries (forward, reverse, or structured) in a single request.
+
+```dart
+var geocoding = GeoCodingApiV6(
+    apiKey: 'API Key', // or use MapBoxSearch.init('API KEY')
+    limit: 5,
+);
+
+Future<ApiResponse<BatchGeocodingResponse>> getBatch() =>
+  geocoding.batch([
+    ForwardQuery(query: "Eiffel Tower", limit: 1),
+    ReverseQuery(location: (lat: 40.6892, long: -74.0445), limit: 1),
+  ]);
+```
+
 ### Static Image
+
 ```dart
-MapBoxStaticImage staticImage = MapBoxStaticImage(
-    apiKey: 'API Key', // dont pass if you have set it in MapBoxSearch.init('API KEY')
+StaticImage staticImage = StaticImage(
+    apiKey: 'API Key', // or use MapBoxSearch.init('API KEY')
   );
 ```
 
 ### Image With Polyline
 ```dart
     String getStaticImageWithPolyline() => staticImage.getStaticUrlWithPolyline(
-      point1: Location(lat: 37.77343, lng: -122.46589),
-      point2: Location(lat: 37.75965, lng: -122.42816),
-      marker1: MapBoxMarker( markerColor: Colors.black, 
-      markerLetter: MakiIcons.aerialway.value, 
-      markerSize: MarkerSize.LARGE),
+      point1: (lat: 37.77343, long: -122.46589),
+      point2: (lat: 37.75965, long: -122.42816),
+      marker1: MapBoxMarker( markerColor: const RgbColor(0, 0, 0),
+          markerLetter: 'p',
+          markerSize: MarkerSize.LARGE),
       marker2: MapBoxMarker(
-          markerColor: Color.rgb(244, 67, 54),
+          markerColor: const RgbColor(244, 67, 54),
           markerLetter: 'q',
           markerSize: MarkerSize.SMALL),
       height: 300,
       width: 600,
-      zoomLevel: 16,
-      style: MapBoxStyle.Mapbox_Dark,
-      path: MapBoxPath(pathColor: Color.rgb(255, 0, 0), pathOpacity: 0.5,     pathWidth: 5),
-      render2x: true);
-``` 
+      zoomLevel: 15.5,
+      style: MapBoxStyle.Dark,
+      path: MapBoxPath(pathColor: const RgbColor(255, 0, 0), pathOpacity: 0.5, pathWidth: 5, pathPolyline: "%7DrpeFxbnjVsFwdAvr%40cHgFor%40jEmAlFmEMwM_FuItCkOi%40wc%40bg%40wBSgM"),
+      render2x: true,
+      center: (lat: 37.766541503617475, long: -122.44702324243272), // Required when auto is false
+      // auto: true, // Alternatively, use auto: true to automatically fit markers and path
+    );
+```
 
 ### Image with Marker
 ```dart
 String getStaticImageWithMarker() => staticImage.getStaticUrlWithMarker(
-  center: Location(lat: 37.77343, lng: -122.46589),
+  center: (lat: 37.77343, long: -122.46589),
   marker: MapBoxMarker(
-      markerColor: Color.rgb(0, 0, 0), markerLetter: 'p', markerSize: MarkerSize.LARGE),
+      markerColor: const RgbColor(0, 0, 0), markerLetter: 'p', markerSize: MarkerSize.LARGE),
   height: 300,
   width: 600,
   zoomLevel: 16,
-  style: MapBoxStyle.Mapbox_Streets,
+  style: MapBoxStyle.Streets,
   render2x: true,
 );
 ```
 
 ### Image without Marker
 ```dart
 String getStaticImageWithoutMarker() => staticImage.getStaticUrlWithoutMarker(
-    center: Location(lat: 37.75965, lng: -122.42816),
+    center: (lat: 37.75965, long: -122.42816),
     height: 300,
     width: 600,
     zoomLevel: 16,
-    style: MapBoxStyle.Mapbox_Outdoors,
+    style: MapBoxStyle.Outdoors,
     render2x: true,
   );
 ```
-# Screenshots
 
-## Static Map Image
+### Example App
+Check out the `example/` directory for a complete Flutter application demonstrating:
+- Forward & Reverse Geocoding
+- Batch Geocoding
+- Static Images (Markers, Polylines, Auto-framing)
 
-<img src="https://github.com/ketanchoyal/mapbox_search/raw/dev/Screenshots/staticImages.png" alt="Static Map Image"/>
 

Screenshots/staticImages.png

@@ -0,0 +1,45 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.build/
+.buildlog/
+.history
+.svn/
+.swiftpm/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+**/doc/api/
+**/ios/Flutter/.last_build_id
+.dart_tool/
+.flutter-plugins-dependencies
+.pub-cache/
+.pub/
+/build/
+/coverage/
+
+# Symbolication related
+app.*.symbols
+
+# Obfuscation related
+app.*.map.json
+
+# Android Studio will place build artifacts here
+/android/app/debug
+/android/app/profile
+/android/app/release

example/.gitignore

@@ -0,0 +1,30 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: "f6ff1529fd6d8af5f706051d9251ac9231c83407"
+  channel: "stable"
+
+project_type: app
+
+# Tracks metadata for the flutter migrate command
+migration:
+  platforms:
+    - platform: root
+      create_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+      base_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+    - platform: macos
+      create_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+      base_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+
+  # User provided section
+
+  # List of Local paths (relative to this file) that should be
+  # ignored by the migrate tool.
+  #
+  # Files that are not part of the templates will be ignored by default.
+  unmanaged_files:
+    - 'lib/main.dart'
+    - 'ios/Runner.xcodeproj/project.pbxproj'

example/.metadata

@@ -0,0 +1,16 @@
+# example_flutter
+
+A new Flutter project.
+
+## Getting Started
+
+This project is a starting point for a Flutter application.
+
+A few resources to get you started if this is your first Flutter project:
+
+- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
+- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)
+
+For help getting started with Flutter development, view the
+[online documentation](https://docs.flutter.dev/), which offers tutorials,
+samples, guidance on mobile development, and a full API reference.

example/README.md

@@ -0,0 +1,28 @@
+# This file configures the analyzer, which statically analyzes Dart code to
+# check for errors, warnings, and lints.
+#
+# The issues identified by the analyzer are surfaced in the UI of Dart-enabled
+# IDEs (https://dart.dev/tools#ides-and-editors). The analyzer can also be
+# invoked from the command line by running `flutter analyze`.
+
+# The following line activates a set of recommended lints for Flutter apps,
+# packages, and plugins designed to encourage good coding practices.
+include: package:flutter_lints/flutter.yaml
+
+linter:
+  # The lint rules applied to this project can be customized in the
+  # section below to disable rules from the `package:flutter_lints/flutter.yaml`
+  # included above or to enable additional rules. A list of all available lints
+  # and their documentation is published at https://dart.dev/lints.
+  #
+  # Instead of disabling a lint rule for the entire project in the
+  # section below, it can also be suppressed for a single line of code
+  # or a specific dart file by using the `// ignore: name_of_lint` and
+  # `// ignore_for_file: name_of_lint` syntax on the line or in the file
+  # producing the lint.
+  rules:
+    # avoid_print: false  # Uncomment to disable the `avoid_print` rule
+    # prefer_single_quotes: true  # Uncomment to enable the `prefer_single_quotes` rule
+
+# Additional information about this file can be found at
+# https://dart.dev/guides/language/analysis-options