Passer au contenu
Capgo - Live Updates for Capacitor Apps Capgo

Commencer

  1. Installez le package

    Fenêtre de terminal
    npm i @capgo/nativegeocoder

  2. Synchronisation avec les projets natifs

    Fenêtre de terminal
    npx cap sync

  3. Configurer les autorisations

    iOS

    Section titled “iOS”

    Ajoutez une description d’utilisation de l’emplacement à votre Info.plist :

    <key>NSLocationWhenInUseUsageDescription</key>
    <string>To convert addresses to coordinates</string>

    Android

    Section titled “Android”

    Ajoutez des autorisations à votre AndroidManifest.xml :

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

Utilisation

Section titled “Utilisation”

Importez le plugin et utilisez ses méthodes de géocodage :

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


// Forward geocoding: Address to coordinates
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: Coordinates to address
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('Street:', address.thoroughfare);
  console.log('City:', address.locality);
  console.log('Country:', address.countryName);
};

API Référence

Section titled “API Référence”

forwardGeocode(options)

Section titled “forwardGeocode(options)”

Convertit une chaîne d’adresse en coordonnées géographiques.

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


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;
}

### Géocode inversé (options)

Convertit les coordonnées géographiques en informations d’adresse.

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

Exemples complets

Section titled “Exemples complets”

Recherche d’adresse avec gestion des erreurs

Section titled “Recherche d’adresse avec gestion des erreurs”
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 failed:', 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 failed:', 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(', ');
  }
}

Composant de sélection d’emplacement

Section titled “Composant de sélection d’emplacement”
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 {
      // Get current coordinates
      const position = await Geolocation.getCurrentPosition();
      this.currentLocation = {
        lat: position.coords.latitude,
        lng: position.coords.longitude
      };


      // Get address for coordinates
      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('Failed to get location:', 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('Search failed:', 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})` : '');
  }
}

## meilleures pratiques

  1. Demandez d’abord les autorisations

    import { Geolocation } from '@capacitor/geolocation';
    

    const requestPermissions = async () => {
      const permissions = await Geolocation.requestPermissions();
      if (permissions.location !== 'granted') {
        throw new Error('Location permission required');
      }
    };

  2. Gérer les erreurs avec élégance

    try {
      const results = await NativeGeocoder.forwardGeocode({
        addressString: address
      });
    } catch (error) {
      // Handle specific error cases
      if (error.message.includes('network')) {
        console.error('Network error');
      } else if (error.message.includes('permission')) {
        console.error('Permission denied');
      }
    }

  3. Utilisez judicieusement maxResults

    • Pour la recherche d’utilisateurs : utilisez 5 à 10 résultats
    • Pour une conversion automatique : utilisez 1 résultat
    • Plus de résultats = réponse plus lente

  4. Cache les résultats lorsque cela est possible

    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;
    }

Différences de plateforme

Section titled “Différences de plateforme”

iOS

Section titled “iOS”
  • Utilise CLGeocoder de CoreLocation
  • Aucune clé API requise
  • Respecte automatiquement les paramètres régionaux de l’utilisateur

Android

Section titled “Android”
  • Utilise Android Géocodeur API
  • Clé Google API en option pour de meilleurs résultats
  • Peut recourir au service Web de Google

API Configuration des touches (Android)

Section titled “API Configuration des touches (Android)”

Pour de meilleurs résultats sur Android, vous pouvez fournir une clé Google API :

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

Problèmes courants

Section titled “Problèmes courants”

  1. Aucun résultat renvoyé

    • Vérifier la connexion Internet
    • Vérifier le format de l’adresse
    • Essayez avec une adresse plus générale

  2. Erreurs d’autorisation

    • Assurez-vous que les autorisations de localisation sont accordées
    • Vérifiez Info.plist/AndroidManifest.xml

  3. Résultats inexacts

    • Utiliser des adresses plus spécifiques
    • Inclure les codes postaux lorsqu’ils sont disponibles
    • Pensez à utiliser des coordonnées pour des emplacements précis