cap-js-geoloc-plugin

🌍 GeolocPlugin - address search/validation and route calculation CAP Plugin

Geolocation plugin for SAP CAP.

Add annotations → The plugin allows, address search, address auto correct and route calculation (duration, distance)

Features

• Address Search: Automatic selection popup
• Address Auto-Correction: Automatic geocoding and normalization
• Route Calculation: Distances and durations in one click
• Optimized Cache: Drastic reduction of API calls
• Multi-transport: Car, bike, pedestrian (depends on chosen provider)

Installation

npm install cap-js-geoloc-plugin

In your package.json:

{
 "cds": {
    "requires": {
      "cap-js-geoloc-plugin": {}
    }
  }
}

Create .env file based on .env.example define PROVIDERS and API keys

Usage

Annotate your fields

// db/schema.cds
entity Routes {
  key ID : UUID;

  // Automatic address search with @AddressSearch
  @AddressSearch: true
  startingPoint : String(500);
  startingPointCoordinates : String(50);

  @AddressSearch: true
  endingPoint : String(500);
  endingPointCoordinates : String(50);

  // Automatic calculation with @RouteCalculation
  @RouteCalculation: {
    from: 'startingPointCoordinates',
    to: 'endingPointCoordinates',
    mode: 'transportMode',
    distanceField: 'distance',
    durationField: 'duration',
    autoCalculate: true  // Automatic calculation on save when coordinates change
  }
  distance : Decimal(10, 2);
  duration : String;
  transportMode : String default 'car';
}

Declare your service (as usual)

// srv/routes-service.cds
using { myapp as db } from '../db/schema';

service RoutesService {
  @odata.draft.enabled
  entity Routes as projection on db.Routes;
}

No JavaScript code needed!** The plugin works automatically with annotations only

The plugin automatically detects and creates:

• @AddressSearch fields → Search popups
• @RouteCalculation fields → Calculate Route button
• All actions (searchAddress_*, calculateRoute, selectAddress) → Auto-generated
• All handlers → Auto-registered
• @AddressAutoCorrect automatic correction adress according to country format and can be parsed to additional fields (country, street...)
• @AddressSearch and @AddressAutoCorrect can be combined

Optional: If you need custom validation, create a service handler:

// srv/routes-service.js (OPTIONAL)
module.exports = function() {
  this.before('CREATE', 'Routes', async (req) => {
    // Your custom validation here
  });
};

User Workflow

Address Search

1. Type "Paris" in the startingPoint field
2. Click on "🔍 Search Starting Point"
3. Choose an address from the popup
4. Done: startingPoint and startingPointCoordinates are automatically filled

Route Calculation

1. Validate both addresses (starting point + destination)
2. Click on "🚗 Calculate Route"
3. Done: distance and duration are automatically calculated

Advanced Features

Automatic Route Calculation on Save

Enable automatic route calculation when coordinates change by setting autoCalculate: true:

entity Routes {
  @RouteCalculation: {
    from: 'startingPointCoordinates',
    to: 'endingPointCoordinates',
    mode: 'transportMode',
    distanceField: 'distance',
    durationField: 'duration',
    autoCalculate: true  // Enables auto-calculation AND auto-refresh in Fiori UI
  }
  distance : Decimal(10, 2);
  duration : String;
  calculatedAt : DateTime;  // Optional: will auto-refresh if present
  mapImageURL : String;     // Optional: will auto-refresh if present
}

How it works:

• When you CREATE a route with both coordinates filled, distance and duration are automatically calculated
• When you UPDATE the from or to coordinates, the route is automatically recalculated
• Fiori UI auto-refreshes: SideEffects are automatically injected - no manual annotations needed!
• If the calculation fails, the save operation continues (non-blocking)
• The "Calculate Route" button is still available for manual recalculation

Auto-Correction with @AddressAutoCorrect

Automatically geocode and normalize addresses when users type them:

entity Routes {
  @AddressAutoCorrect: {
    correctedField: 'correctedStartingPoint',
    coordinatesField: 'startingPointCoordinates',
    cityField: 'startingPointCity',
    streetField: 'startingPointStreet'
  }
  startingPoint : String(500);          // User input
  correctedStartingPoint : String(500);  // Auto-filled with formatted address
  startingPointCoordinates : String(50); // Auto-filled with coordinates
  startingPointCity : String(100);       // Auto-filled with city
  startingPointStreet : String(100);     // Auto-filled with street
}

How it works:

1. User types: "21 rue liberte dijon" (with typos)
2. On CREATE/UPDATE, the plugin automatically:
   • Geocodes the address
   • Fills correctedStartingPoint: "21 Rue de la Liberté, 21000 Dijon, France" (formatted by country)
   • Fills startingPointCoordinates: "47.3220, 5.0415"
   • Fills startingPointCity: "Dijon"
   • Fills startingPointStreet: "Rue de la Liberté"

Country-specific formatting:

The plugin automatically formats addresses according to each country's conventions:

• France: "23 rue des Pigeons, 67000 Strasbourg"
• Germany: "Musterstraße 23, 10115 Berlin"
• UK: "10 Downing Street, London SW1A 2AA"
• USA: "123 Main Street, New York, NY 10001"
• Spain: "Calle Mayor 23, 28013 Madrid"
• Italy: "Via Roma 123, 00100 Roma"
• And 20+ more countries...

The plugin detects the country from geocoding results (works with country names in multiple languages: English, French, German, Spanish, Italian, Dutch, and native names).

Manual override for non-existent addresses:

For new streets or addresses not yet in geocoding databases, you can bypass automatic geocoding:

entity Routes {
  @AddressAutoCorrect: {
    correctedField: 'correctedStartingPoint',
    coordinatesField: 'startingPointCoordinates',
    manualOverrideField: 'isManualAddress'  // Flag to skip geocoding
  }
  startingPoint : String(500);
  correctedStartingPoint : String(500);
  startingPointCoordinates : String(50);
  isManualAddress : Boolean default false;  // Set to true to skip geocoding
}

How it works:

• If isManualAddress = true → geocoding is skipped, you can enter any address and coordinates manually
• If isManualAddress = false → normal geocoding and validation
• Useful for construction sites, new developments, or addresses not yet in mapping databases

Simple notation (only corrected field):

@AddressAutoCorrect: 'correctedStartingPoint'
startingPoint : String(500);
correctedStartingPoint : String(500);

Fiori Interface (Optional)

If you want to customize the Fiori UI, add annotations:

// app/routes/annotations.cds
using { RoutesService } from '../../srv/routes-service';

// Buttons in the header
annotate RoutesService.Routes with @(
  UI.Identification : [
    {
      $Type : 'UI.DataFieldForAction',
      Action : 'RoutesService.calculateRoute',
      Label : '🚗 Calculate Route',
      ![@UI.Hidden] : {$edmJson: {$Path: 'IsActiveEntity'}}
    }
  ]
);

Configuration (Optional)

Create a .env file to customize:

# Geocoding (Free Nominatim by default)
GEOLOC_GEOCODING_PROVIDER=nominatim
GEOLOC_GEOCODING_DELAY=1000  # Rate limit: ms between requests (1000 = 1 req/sec)

# Routing (Free OSRM by default)
GEOLOC_ROUTING_PROVIDER=osrm
GEOLOC_ROUTING_PROFILE=car  # car | bike | foot

# Cache
GEOLOC_CACHE_ENABLED=true
GEOLOC_CACHE_TTL=2592000  # 30 days

.env.example:
# =============================================================================
# GeolocPlugin Configuration
# =============================================================================

# -----------------------------------------------------------------------------
# ROUTING - Real distance calculation by route
# -----------------------------------------------------------------------------

# Routing provider: 'osrm' | 'openrouteservice' | 'locationiq' | 'googlemaps' | 'mapbox' | 'here'
# - osrm: FREE, unlimited, no API key required (recommended)
# - openrouteservice: Free up to 2,500 req/day (API key required)
# - locationiq: Free up to 5,000 req/day (API key required)
# - googlemaps: Pay-as-you-go (API key required, $5 per 1000 requests)
# - mapbox: Free up to 100,000 req/month (API key required)
# - here: Free up to 250,000 req/month (API key required)
GEOLOC_ROUTING_PROVIDER=osrm

# Default transport profile: 'car' | 'bike' | 'foot'
GEOLOC_ROUTING_PROFILE=car

# Fallback to OSRM on error: 'true' | 'false'
GEOLOC_ROUTING_FALLBACK=true

# -----------------------------------------------------------------------------
# API KEYS (optional - only if you're not using OSRM)
# -----------------------------------------------------------------------------

# OpenRouteService API Key (free: https://openrouteservice.org/dev/#/signup)
OPENROUTESERVICE_API_KEY=

# LocationIQ API Key (free: https://locationiq.com/register)
LOCATIONIQ_API_KEY=

# Google Maps API Key (pay-as-you-go: https://console.cloud.google.com/google/maps-apis)
# Enable "Directions API" in your Google Cloud Console
GOOGLE_MAPS_API_KEY=

# Mapbox API Key (free: https://account.mapbox.com/auth/signup/)
# Free tier: 100,000 requests/month
MAPBOX_API_KEY=

# HERE API Key (free: https://developer.here.com/sign-up)
# Free tier: 250,000 requests/month
HERE_API_KEY=

# -----------------------------------------------------------------------------
# GEOCODING - Address validation and normalization
# -----------------------------------------------------------------------------

# Geocoding provider: 'nominatim' | 'openrouteservice' | 'locationiq' | 'googlemaps' | 'here' | 'mapbox'
# - nominatim: FREE, limited to 1 req/sec (no API key required, recommended for development)
# - openrouteservice: Uses your existing quota (API key required, shared with routing)
#   does not allow full address search in free mode
# - locationiq: Uses your existing quota (API key required, shared with routing)
# - googlemaps: Pay-as-you-go, excellent quality (API key required, enable "Geocoding API")
# - here: Free up to 250,000 req/month, excellent quality (API key required)
# - mapbox: Free up to 100,000 req/month, excellent quality (API key required)
# Note: API keys for googlemaps, here, and mapbox are shared with routing if configured
GEOLOC_GEOCODING_PROVIDER=nominatim

# Rate limiting: delay in milliseconds between geocoding requests (applies to ALL providers)
# Default: 1000ms (1 second) - respects Nominatim usage policy
# Set to 0 to disable rate limiting (useful for paid APIs with higher limits)
# Examples: 1000 = 1 req/sec | 500 = 2 req/sec | 200 = 5 req/sec | 0 = no limit
GEOLOC_GEOCODING_DELAY=1000

# -----------------------------------------------------------------------------
# CACHE - API call optimization
# -----------------------------------------------------------------------------

# Enable cache: 'true' | 'false'
GEOLOC_CACHE_ENABLED=true

# Cache time-to-live in seconds (30 days = 2592000)
GEOLOC_CACHE_TTL=2592000

# Maximum number of cache entries
GEOLOC_CACHE_MAX_SIZE=1000

# =============================================================================
# CONFIGURATION EXAMPLES
# =============================================================================

# -----------------------------------------------------------------------------
# Example 1: FREE configuration (OSRM + Nominatim)
# -----------------------------------------------------------------------------
# GEOLOC_ROUTING_PROVIDER=osrm
# GEOLOC_ROUTING_PROFILE=car
# GEOLOC_GEOCODING_PROVIDER=nominatim
# GEOLOC_CACHE_ENABLED=true
#
# → 100% free, unlimited (OSRM)
# → No API key required

# -----------------------------------------------------------------------------
# Example 2: Production with OpenRouteService (2,500 req/day)
# -----------------------------------------------------------------------------
# GEOLOC_ROUTING_PROVIDER=openrouteservice
# GEOLOC_ROUTING_PROFILE=car
# GEOLOC_ROUTING_FALLBACK=true
# GEOLOC_GEOCODING_PROVIDER=openrouteservice
# OPENROUTESERVICE_API_KEY=your-api-key-here
# GEOLOC_CACHE_ENABLED=true
#
# → Routing AND Geocoding via OpenRouteService (shared quota)
# → Fallback to OSRM if routing quota exceeded

# -----------------------------------------------------------------------------
# Example 3: Production with LocationIQ (5,000 req/day)
# -----------------------------------------------------------------------------
# GEOLOC_ROUTING_PROVIDER=locationiq
# GEOLOC_ROUTING_PROFILE=car
# GEOLOC_ROUTING_FALLBACK=true
# GEOLOC_GEOCODING_PROVIDER=locationiq
# LOCATIONIQ_API_KEY=your-api-key-here
# GEOLOC_CACHE_ENABLED=true
#
# → Routing AND Geocoding via LocationIQ (shared quota)
# → Fallback to OSRM if routing quota exceeded

# -----------------------------------------------------------------------------
# Example 4: Bike application
# -----------------------------------------------------------------------------
# GEOLOC_ROUTING_PROVIDER=osrm
# GEOLOC_ROUTING_PROFILE=bike
# GEOLOC_CACHE_ENABLED=true
#
# → Uses bike paths for routing

# -----------------------------------------------------------------------------
# Example 5: Mix OSRM (routing) + LocationIQ (geocoding)
# -----------------------------------------------------------------------------
# GEOLOC_ROUTING_PROVIDER=osrm
# GEOLOC_ROUTING_PROFILE=car
# GEOLOC_GEOCODING_PROVIDER=locationiq
# LOCATIONIQ_API_KEY=your-api-key-here
# GEOLOC_CACHE_ENABLED=true
#
# → Free unlimited routing (OSRM)
# → Geocoding via LocationIQ (5,000 req/day)
# → Optimal: LocationIQ quota saved for geocoding only

# -----------------------------------------------------------------------------
# Example 6: Disable cache (development/debug)
# -----------------------------------------------------------------------------
# GEOLOC_ROUTING_PROVIDER=osrm
# GEOLOC_GEOCODING_PROVIDER=nominatim
# GEOLOC_CACHE_ENABLED=false
#
# → All requests call the API (useful for testing)

# -----------------------------------------------------------------------------
# Example 7: Production with Google Maps Directions API
# -----------------------------------------------------------------------------
# GEOLOC_ROUTING_PROVIDER=googlemaps
# GEOLOC_ROUTING_PROFILE=car
# GEOLOC_ROUTING_FALLBACK=true
# GOOGLE_MAPS_API_KEY=your-api-key-here
# GEOLOC_GEOCODING_PROVIDER=nominatim
# GEOLOC_CACHE_ENABLED=true
#
# → High accuracy routing via Google Maps (pay-as-you-go)
# → Fallback to OSRM if quota exceeded
# → Free geocoding via Nominatim

# -----------------------------------------------------------------------------
# Example 8: Production with Mapbox Directions API (100k req/month free)
# -----------------------------------------------------------------------------
# GEOLOC_ROUTING_PROVIDER=mapbox
# GEOLOC_ROUTING_PROFILE=car
# GEOLOC_ROUTING_FALLBACK=true
# MAPBOX_API_KEY=your-api-key-here
# GEOLOC_GEOCODING_PROVIDER=nominatim
# GEOLOC_CACHE_ENABLED=true
#
# → Routing via Mapbox (100,000 free requests/month)
# → Fallback to OSRM if quota exceeded
# → Free geocoding via Nominatim

# -----------------------------------------------------------------------------
# Example 9: Production with HERE Maps Routing API (250k req/month free)
# -----------------------------------------------------------------------------
# GEOLOC_ROUTING_PROVIDER=here
# GEOLOC_ROUTING_PROFILE=car
# GEOLOC_ROUTING_FALLBACK=true
# HERE_API_KEY=your-api-key-here
# GEOLOC_GEOCODING_PROVIDER=nominatim
# GEOLOC_CACHE_ENABLED=true
#
# → Routing via HERE Maps (250,000 free requests/month)
# → Fallback to OSRM if quota exceeded
# → Free geocoding via Nominatim
# → Best free tier option (highest quota)

Available Providers

Routing Providers

Geocoding Providers (Address Search)

*Fair use policy applies (no SLA)

Programmatic API (Optional)

If you want to use the plugin directly in your code:

Geocoding

const GeolocPlugin = require('geoloc-plugin');

// Validate an address
const result = await GeolocPlugin.geocoding.validateAddress('Paris, France');
// → { formatted: "Paris, Île-de-France, France", coordinates: "48.8566,2.3522", ... }

// Search for multiple suggestions
const results = await GeolocPlugin.geocoding.searchAddress('Lyon', 10);
// → { found: true, count: 10, results: [...] }

Routing

// Calculate a route
const route = await GeolocPlugin.routing.calculateRoute(
  '48.8566,2.3522',  // Paris
  '45.7640,4.8357',  // Lyon
  'car'
);
// → { distanceKm: 465.87, durationMinutes: 297, formattedDuration: "4h 57min" }

🎓 Complete Documentation

• README.md - This file
• EXAMPLES.md - Detailed examples
• CHANGELOG.md - Version history

Development

Contributing

Contributions are welcome! Create an issue or pull request.