EXIF Gallery Documentation

Overview

Capacitor EXIF Gallery is the only Capacitor plugin that provides native GPS-based photo filtering on both iOS and Android. It reads EXIF metadata directly on the native layer — in Swift and Kotlin — to filter device photos by GPS location, route polylines, and date ranges before the user makes a selection.

Unlike standard gallery plugins that simply open the photo picker, EXIF Gallery adds an intelligent filtering layer. This is essential for applications that need location-verified photo evidence, such as insurance claims, construction documentation, real estate listings, and travel journals.

How It Compares

At a Glance

• ✓Filter photos by GPS radius or route polyline
• ✓Filter by date/time range
• ✓Combine location + time filters (AND logic)
• ✓Extract EXIF metadata (GPS, timestamps)
• ✓Intelligent fallback when too few results
• ✓Native UI in English, German, French, Spanish
• ✓Custom UI text overrides
• ✓iOS 15+ & Android 7.0+ (API 24)
• ✓Capacitor 8 compatible
• ✓Free for debug builds — license required for production

Platform Support

Quick Start

1. Install

Install the plugin via npm and sync your Capacitor project.

1npm install @kesbyte/capacitor-exif-gallery
2npx cap sync

2. Configure License Key

Required for production builds only. Debug builds work without a license for testing. Purchase your license key at https://plugins.kesbyte-digital.com/exif-gallery

iOS Configuration (Info.plist)

Open your ios/App/App/Info.plist and add:

1<key>KBExifGalleryLicense</key>
2<string>YOUR_LICENSE_KEY_HERE</string>

Android Configuration (AndroidManifest.xml)

Open your android/app/src/main/AndroidManifest.xml and add inside the '<'application'>' tag:

1<application>
2    <!-- Other configuration... -->
3
4    <meta-data
5        android:name="com.kesbytedigital.exifgallery.LICENSE_KEY"
6        android:value="YOUR_LICENSE_KEY_HERE" />
7
8</application>

Validation Behavior

The license is validated at the moment you call pick(), not during initialize(). This ensures fast app startup while still enforcing licensing before the plugin is actually used.

Troubleshooting

3. Configure Permissions

iOS Permissions (Info.plist)

Add the following to your ios/App/App/Info.plist:

1<key>NSPhotoLibraryUsageDescription</key>
2<string>This app needs access to your photo library to filter and select images</string>
3
4<key>NSLocationWhenInUseUsageDescription</key>
5<string>This app uses your location to enhance image filtering capabilities</string>

• NSPhotoLibraryUsageDescription: Required for reading photos from the library
• NSLocationWhenInUseUsageDescription: Required for location-based filtering (only when app is in use)

Android Permissions (AndroidManifest.xml)

Add the following to your android/app/src/main/AndroidManifest.xml:

1<!-- Photo Library Permissions -->
2<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
3<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
4
5<!-- Location Permission -->
6<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

• READ_MEDIA_IMAGES: For Android 13+ (API 33+), granular image access
• READ_EXTERNAL_STORAGE: For Android 12 and below (API 32 or less), legacy storage access
• ACCESS_FINE_LOCATION: Required for location-based filtering

4. Initialize

Call initialize() once at app startup before using pick().

1import { ExifGallery } from '@kesbyte/capacitor-exif-gallery';
2
3// During app initialization
4await ExifGallery.initialize();

5. Open Gallery with Filters

Call pick() with optional filter configuration to open the native gallery.

1const result = await ExifGallery.pick({
2  filter: {
3    location: {
4      coordinates: [{ lat: 52.52, lng: 13.40 }],
5      radius: 5000  // 5km radius
6    }
7  }
8});
9
10// Access selected images
11if (!result.cancelled) {
12  result.images.forEach(image => {
13    console.log(`Selected: ${image.uri}`);
14    console.log(`Location: ${image.exif?.lat}, ${image.exif?.lng}`);
15    console.log(`Timestamp: ${image.exif?.timestamp}`);
16  });
17}

Features in Detail

Location-Based Filtering

Filter images by geographic location with two flexible input formats. You can specify individual GPS coordinates or use encoded polylines from services like Google Maps.

Using coordinates

Pass an array of GPS coordinates to filter images within a specified radius of each point.

1const result = await ExifGallery.pick({
2  filter: {
3    location: {
4      coordinates: [
5        { lat: 52.5163, lng: 13.3777 },  // Berlin
6        { lat: 48.1374, lng: 11.5755 }   // Munich
7      ],
8      radius: 10000  // 10km around each point
9    }
10  }
11});

Using encoded polylines (Google Maps format)

Pass an encoded polyline string from Google Directions API or similar services to filter images along a route.

1const result = await ExifGallery.pick({
2  filter: {
3    location: {
4      polyline: route,  // Encoded string like "_p~iF~ps|U_ulLnnqC"
5      radius: 5000     // 5km corridor around route
6    }
7  }
8});

Why encoded polylines?

• 92% smaller payload (5KB to 400 bytes for 100 points)
• URL-safe format
• Direct compatibility with Google Maps, Mapbox, OpenStreetMap

Time Range Filtering

Select images taken within a specific date/time window. The plugin reads the EXIF DateTimeOriginal timestamp — the actual capture moment, not the file modification date.

1const result = await ExifGallery.pick({
2  filter: {
3    timeRange: {
4      start: new Date('2025-01-01'),
5      end: new Date('2025-12-31')
6    }
7  }
8});

Combined Filters (Location AND Time)

Apply multiple filters simultaneously. When both location and time filters are provided, images must match ALL criteria (AND logic).

1const result = await ExifGallery.pick({
2  filter: {
3    location: {
4      coordinates: [{ lat: 52.52, lng: 13.40 }],
5      radius: 5000
6    },
7    timeRange: {
8      start: new Date('2025-01-01'),
9      end: new Date('2025-12-31')
10    }
11  }
12});

EXIF Metadata Extraction

Access GPS coordinates and timestamp information from every selected image. The EXIF data is read natively without copying files to temporary directories.

1const result = await ExifGallery.pick();
2
3result.images.forEach(image => {
4  const exif = image.exif;
5  if (exif) {
6    console.log(`Latitude: ${exif.lat}`);
7    console.log(`Longitude: ${exif.lng}`);
8    console.log(`Taken at: ${exif.timestamp}`);
9  }
10});

Custom UI Text

Override any default UI string in any language. Translations are passed at initialization and merged with the built-in defaults.

1await ExifGallery.initialize({
2  locale: 'en',
3  customTexts: {
4    galleryTitle: 'Select Your Photos',
5    selectButton: 'Pick Images',
6    cancelButton: 'Close',
7    filterDialogTitle: 'Advanced Filters',
8    emptyMessage: 'No photos found matching your criteria'
9  }
10});

Automatic Permission Handling

The plugin requests photo library and location permissions just-in-time when pick() is called. You can optionally request permissions upfront during onboarding by setting requestPermissionsUpfront to true.

1await ExifGallery.initialize({
2  requestPermissionsUpfront: true
3});

Usage Examples

1import { ExifGallery } from '@kesbyte/capacitor-exif-gallery';
2
3const result = await ExifGallery.pick();
4
5if (!result.cancelled) {
6  const fileUris = result.images.map(img => img.uri);
7  console.log(`Selected ${fileUris.length} images`);
8}

1const result = await ExifGallery.pick({
2  filter: {
3    location: {
4      coordinates: [{ lat: 52.52, lng: 13.40 }],
5      radius: 1000  // 1km - strict radius
6    }
7  },
8  fallbackThreshold: 5  // Switch to time filter if < 5 images found
9});

1const result = await ExifGallery.pick({
2  filter: {
3    location: {
4      coordinates: [{ lat: 48.85, lng: 2.29 }],  // Paris
5      radius: 20000
6    }
7  },
8  allowManualAdjustment: false  // User cannot change filters
9});

1const result = await ExifGallery.pick({
2  filter: {
3    timeRange: {
4      start: new Date('2025-01-01'),
5      end: new Date('2025-12-31')
6    }
7  },
8  allowManualAdjustment: true  // Default - user can adjust
9});

1// German UI
2await ExifGallery.initialize({ locale: 'de' });
3const resultDE = await ExifGallery.pick();
4
5// French UI
6await ExifGallery.initialize({ locale: 'fr' });
7const resultFR = await ExifGallery.pick();
8
9// Spanish UI
10await ExifGallery.initialize({ locale: 'es' });
11const resultES = await ExifGallery.pick();

1// Your recorded GPS points from a Strava activity or hiking app
2const routePolyline = "_p~iF~ps|U_ulLnnqC_seK`xwE";
3
4const result = await ExifGallery.pick({
5  filter: {
6    location: {
7      polyline: routePolyline,
8      radius: 2000  // 2km corridor on each side of route
9    }
10  }
11});
12
13console.log(`Found ${result.images.length} photos along your route`);

API Reference

Methods

Interfaces

1type SupportedLocale = 'en' | 'de' | 'fr' | 'es';

Licensing

Capacitor EXIF Gallery uses a commercial license model. The plugin is free for debug/development builds, and requires a valid license key for production builds.

How It Works

1. 1Development: Install and test the plugin freely in debug builds
2. 2Production: Purchase a license key before releasing your app
3. 3Integration: Add the license key to your app configuration (Info.plist / AndroidManifest.xml)
4. 4Build: Production builds validate the license automatically when pick() is called

Frequently Asked Questions

Support

Need help integrating the EXIF Gallery plugin? Here are the available support channels: