Cercalia SDK for TypeScript

The official, type-safe TypeScript SDK for Cercalia web services. Built by Nexus Geographics, this SDK enables you to integrate powerful location-based features like geocoding, routing, and POI search into your Node.js and browser applications.

🌟 About Cercalia

Cercalia is a comprehensive SaaS geospatial platform developed by Nexus Geographics, a leading company in geospatial technology and innovation. Cercalia provides enterprise-grade mapping, geocoding, routing, and location intelligence services, with exceptional coverage of European markets and advanced spatial analysis capabilities.

Trusted by leading enterprises across logistics, emergency services, fleet management, and smart city solutions, Cercalia delivers the precision and reliability that mission-critical applications demand.

Why Choose Cercalia?

• Global Coverage: Based on TomTom content, enriched with OpenStreetMap data
• European Leadership: Unmatched data quality and coverage across all of Europe, with particular strength in Western, Central, and Southern regions—ideal for pan-European applications and businesses seeking reliable, up-to-date geospatial information
• Live & Historical Traffic Data: Global coverage of road incidents, congestion, closures, traffic-based ETAs, and routing with live or expected traffic
• Enterprise-Ready: Built for scale with high availability, performance SLAs, and dedicated support
• Comprehensive Platform: 12+ geospatial services accessible through modern, type-safe SDKs
• Innovation Leader: Powered by Nexus Geographics' 25+ years of GIS expertise

Learn More:

• 🌐 Official Website: www.cercalia.com
• 📝 Sign Up: clients.cercalia.com/register
• 🏢 Nexus Geographics: www.nexusgeographics.com
• 🐦 Twitter: @nexusgeographics
• 💼 LinkedIn: Nexus Geographics

✨ Features

• 🛡️ Type-Safe: Built with TypeScript strict mode—zero any types, full IntelliSense support
• 🌐 Universal: Works seamlessly in Node.js (ESM/CommonJS) and browsers (via bundler)
• 📦 Modern Architecture: Clean, modular design with tree-shakeable exports
• 🔄 Comprehensive Services: Access 12+ geospatial services
• ⚡ Resilient: Built-in retry logic and robust error handling
• 📝 Well-Documented: Inline JSDoc comments and comprehensive examples

🚀 Installation

npm install @cercalia/sdk
# or
yarn add @cercalia/sdk
# or
pnpm add @cercalia/sdk

🔑 Getting Started

1. Get Your API Key

Register for a free Cercalia account and obtain your API key:

👉 Register here

2. Quick Example

import { setConfig, GeocodingService, RoutingService } from '@cercalia/cercalia-sdk';

// Configure the SDK
setConfig({
  cercalia: {
    apiKey: 'YOUR_API_KEY_HERE',
    baseUrl: 'https://lb.cercalia.com/services/v2/json'
  }
});

// Geocode an address
const geocoding = new GeocodingService();
const locations = await geocoding.geocode({
  street: 'Paseo de la Castellana, 1',
  locality: 'Madrid',
  countryCode: 'ESP'
});

console.log(`Found: ${locations[0].name}`);
console.log(`Coordinates: ${locations[0].coord.lat}, ${locations[0].coord.lng}`);

// Calculate a route
const routing = new RoutingService();
const route = await routing.calculateRoute(
  locations[0].coord,
  { lat: 41.387015, lng: 2.170047 } // Barcelona
);

console.log(`Distance: ${(route.distance / 1000).toFixed(2)} km`);
console.log(`Duration: ${(route.duration / 60).toFixed(0)} minutes`);

Security Note: Never expose your API key in client-side code for production applications. Use environment variables or a backend proxy to authenticate requests.

🛠️ Available Services

| Service | Description | Class | |---------|-------------|-------| | Geocoding | Convert addresses to geographic coordinates | GeocodingService | | Reverse Geocoding | Get addresses from coordinates | ReverseGeocodingService | | Routing | Calculate optimal routes with turn-by-turn directions | RoutingService | | Suggest | Autocomplete and place search suggestions | SuggestService | | POI Search | Find Points of Interest near locations | POIService | | Isochrones | Calculate reachability areas (drive time/distance) | IsochroneService | | Proximity | Distance calculations and nearest neighbor search | ProximityService | | Geofencing | Point-in-polygon and spatial boundary operations | GeofencingService | | Static Maps | Generate static map images | StaticMapsService | | Snap to Road | Match GPS traces to road network | SnapToRoadService | | Geoment | Geographic element queries and geometries | GeomentService |

📚 Documentation

• 📖 SDK API Reference: docs.cercalia.com/sdk/docs/ts/
• 📘 Official Cercalia API Docs: docs.cercalia.com/docs/
• 💡 Examples: Browse the examples/ directory for runnable code samples

🤝 Support & Community

Need help or have questions?

• Documentation: docs.cercalia.com
• Support Portal: Available through your Cercalia dashboard
• Issues: GitHub Issues

📄 License

This SDK is provided for use with Cercalia web services. Please refer to your Cercalia service agreement for terms of use.