Memulai

1. Instal paket

   npm

   npm i @capgo/nativegeocoder

   pnpm

   pnpm add @capgo/nativegeocoder

   yarn

   yarn add @capgo/nativegeocoder

   bun

   bun add @capgo/nativegeocoder

2. Sinkronkan dengan proyek native

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Konfigurasi izin

   iOS

   Tambahkan deskripsi penggunaan lokasi ke Info.plist Anda:

   <key>NSLocationWhenInUseUsageDescription</key>
   <string>Untuk mengonversi alamat ke koordinat</string>

   Android

   Tambahkan izin ke AndroidManifest.xml Anda:

   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Penggunaan

Impor plugin dan gunakan metode geocoding-nya:

import { NativeGeocoder } from '@capgo/nativegeocoder';

// Forward geocoding: Alamat ke koordinat
const forwardGeocode = async () => {
  const results = await NativeGeocoder.forwardGeocode({
    addressString: '1600 Amphitheatre Parkway, Mountain View, CA',
    useLocale: true,
    maxResults: 1
  });

  const location = results.addresses[0];
  console.log('Latitude:', location.latitude);
  console.log('Longitude:', location.longitude);
};

// Reverse geocoding: Koordinat ke alamat
const reverseGeocode = async () => {
  const results = await NativeGeocoder.reverseGeocode({
    latitude: 37.4220656,
    longitude: -122.0840897,
    useLocale: true,
    maxResults: 1
  });

  const address = results.addresses[0];
  console.log('Jalan:', address.thoroughfare);
  console.log('Kota:', address.locality);
  console.log('Negara:', address.countryName);
};

Referensi API

forwardGeocode(options)

Mengonversi string alamat ke koordinat geografis.

interface ForwardGeocodeOptions {
  addressString: string;
  useLocale?: boolean;
  maxResults?: number;
  apiKey?: string; // Android saja
}

interface GeocodeResult {
  addresses: Address[];
}

interface Address {
  latitude: number;
  longitude: number;
  countryCode?: string;
  countryName?: string;
  postalCode?: string;
  administrativeArea?: string;
  subAdministrativeArea?: string;
  locality?: string;
  subLocality?: string;
  thoroughfare?: string;
  subThoroughfare?: string;
}

reverseGeocode(options)

Mengonversi koordinat geografis ke informasi alamat.

interface ReverseGeocodeOptions {
  latitude: number;
  longitude: number;
  useLocale?: boolean;
  maxResults?: number;
  apiKey?: string; // Android saja
}

Contoh Lengkap

Pencarian Alamat dengan Penanganan Error

import { NativeGeocoder } from '@capgo/nativegeocoder';

export class GeocodingService {
  async searchAddress(address: string): Promise<{lat: number, lng: number} | null> {
    try {
      const results = await NativeGeocoder.forwardGeocode({
        addressString: address,
        useLocale: true,
        maxResults: 5
      });

      if (results.addresses.length > 0) {
        const location = results.addresses[0];
        return {
          lat: location.latitude,
          lng: location.longitude
        };
      }

      return null;
    } catch (error) {
      console.error('Geocoding gagal:', error);
      return null;
    }
  }

  async getAddressFromCoordinates(lat: number, lng: number): Promise<string | null> {
    try {
      const results = await NativeGeocoder.reverseGeocode({
        latitude: lat,
        longitude: lng,
        useLocale: true,
        maxResults: 1
      });

      if (results.addresses.length > 0) {
        const address = results.addresses[0];
        return this.formatAddress(address);
      }

      return null;
    } catch (error) {
      console.error('Reverse geocoding gagal:', error);
      return null;
    }
  }

  private formatAddress(address: Address): string {
    const parts = [
      address.subThoroughfare,
      address.thoroughfare,
      address.locality,
      address.administrativeArea,
      address.postalCode,
      address.countryName
    ].filter(part => part != null && part !== '');

    return parts.join(', ');
  }
}

Komponen Pemilih Lokasi

import { NativeGeocoder } from '@capgo/nativegeocoder';
import { Geolocation } from '@capacitor/geolocation';

export class LocationPicker {
  currentLocation: { lat: number; lng: number } | null = null;
  currentAddress: string = '';

  async getCurrentLocation() {
    try {
      // Dapatkan koordinat saat ini
      const position = await Geolocation.getCurrentPosition();
      this.currentLocation = {
        lat: position.coords.latitude,
        lng: position.coords.longitude
      };

      // Dapatkan alamat untuk koordinat
      const results = await NativeGeocoder.reverseGeocode({
        latitude: this.currentLocation.lat,
        longitude: this.currentLocation.lng,
        useLocale: true,
        maxResults: 1
      });

      if (results.addresses.length > 0) {
        const address = results.addresses[0];
        this.currentAddress = [
          address.thoroughfare,
          address.locality,
          address.countryName
        ].filter(Boolean).join(', ');
      }
    } catch (error) {
      console.error('Gagal mendapatkan lokasi:', error);
    }
  }

  async searchLocation(query: string) {
    try {
      const results = await NativeGeocoder.forwardGeocode({
        addressString: query,
        useLocale: true,
        maxResults: 10
      });

      return results.addresses.map(address => ({
        coordinates: {
          lat: address.latitude,
          lng: address.longitude
        },
        displayName: this.formatDisplayName(address)
      }));
    } catch (error) {
      console.error('Pencarian gagal:', error);
      return [];
    }
  }

  private formatDisplayName(address: Address): string {
    const mainPart = [
      address.thoroughfare,
      address.locality
    ].filter(Boolean).join(', ');

    const subPart = [
      address.administrativeArea,
      address.countryName
    ].filter(Boolean).join(', ');

    return mainPart + (subPart ? ` (${subPart})` : '');
  }
}

Praktik Terbaik

1. Minta izin terlebih dahulu

   import { Geolocation } from '@capacitor/geolocation';
   
   const requestPermissions = async () => {
     const permissions = await Geolocation.requestPermissions();
     if (permissions.location !== 'granted') {
       throw new Error('Izin lokasi diperlukan');
     }
   };

2. Tangani error dengan baik

   try {
     const results = await NativeGeocoder.forwardGeocode({
       addressString: address
     });
   } catch (error) {
     // Tangani kasus error spesifik
     if (error.message.includes('network')) {
       console.error('Error jaringan');
     } else if (error.message.includes('permission')) {
       console.error('Izin ditolak');
     }
   }

3. Gunakan maxResults dengan bijak

   • Untuk pencarian pengguna: Gunakan 5-10 hasil
   • Untuk konversi otomatis: Gunakan 1 hasil
   • Lebih banyak hasil = respons lebih lambat

4. Cache hasil bila memungkinkan

   const geocodeCache = new Map();
   
   async function geocodeWithCache(address: string) {
     if (geocodeCache.has(address)) {
       return geocodeCache.get(address);
     }
   
     const result = await NativeGeocoder.forwardGeocode({
       addressString: address
     });
   
     geocodeCache.set(address, result);
     return result;
   }

Perbedaan Platform

iOS

• Menggunakan CLGeocoder dari CoreLocation
• Tidak perlu API key
• Menghormati locale pengguna secara otomatis

Android

• Menggunakan Android Geocoder API
• API key Google opsional untuk hasil lebih baik
• Mungkin fallback ke layanan web Google

Konfigurasi API Key (Android)

Untuk hasil lebih baik di Android, Anda dapat menyediakan API key Google:

await NativeGeocoder.forwardGeocode({
  addressString: address,
  apiKey: 'YOUR_GOOGLE_API_KEY' // Android saja
});

Masalah Umum

1. Tidak ada hasil yang dikembalikan

   • Periksa koneksi internet
   • Verifikasi format alamat
   • Coba dengan alamat yang lebih umum

2. Error izin

   • Pastikan izin lokasi diberikan
   • Periksa Info.plist/AndroidManifest.xml

3. Hasil tidak akurat

   • Gunakan alamat yang lebih spesifik
   • Sertakan kode pos jika tersedia
   • Pertimbangkan menggunakan koordinat untuk lokasi yang tepat