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
Copy

🔑 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`);
Copy

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.

---

Built with ❤️ by Nexus Geographics
www.cercalia.com • Twitter • LinkedIn