OpenAPI Implementation

OpenAPI gateway for Cercalia Core REST services with OpenAPI 3.0 specs, Swagger UI, and production-ready REST endpoints.

4 minute read

What is this? The OpenAPI Implementation is a type-safe REST wrapper around the Core REST API. It provides cleaner endpoints, automatic validation, interactive documentation, and production-ready features like health checks and retry logic.

Explore the Hosted Swagger UI

Prefer to explore the API without running it locally? Use our hosted OpenAPI + Swagger interface to browse endpoints, view schemas, and test requests instantly.

Open Swagger Documentation →

Overview

While the Core REST API gives you direct access to Cercalia’s geospatial engine, the OpenAPI Implementation adds a modern abstraction layer on top of it. Think of it as a “developer-friendly gateway” that:

Transforms Legacy to Modern REST

Converts Cercalia's query-string API into clean, RESTful endpoints following best practices.

OpenAPI 3.0 Specification

Full OpenAPI spec enables code generation for any language and interactive Swagger UI documentation.

Request Validation

Automatic validation of all parameters with clear error messages before reaching the backend.

Production-Ready

Health checks, structured logging, retry logic, and Docker support out of the box.

When to Use This vs Core REST API

Use Case	Recommendation
Building a new application from scratch	OpenAPI Implementation - Better DX, type safety, modern patterns
Migrating an existing Cercalia integration	Core REST API - Direct compatibility with existing code
Generating client SDKs for unsupported languages	OpenAPI Implementation - Use the OpenAPI spec with code generators
Direct HTTP integration without middleware	Core REST API - Fewer moving parts, direct access
Need Swagger UI for team onboarding	OpenAPI Implementation - Interactive docs included
Maximum control over request/response handling	Core REST API - No abstraction layer

Available Services

The OpenAPI Implementation wraps 11 Core REST API services with enhanced endpoints:

Service	Endpoint	Core API Equivalent
Geocoding	`GET /v1/geocoding`	Geocoding
Reverse Geocoding	`GET /v1/reverse-geocoding`	Reverse Geocoding
Suggest	`GET /v1/suggest`	Suggest
Routing	`GET /v1/routing`	Routing
Isochrone	`GET /v1/isochrone`	Isochrones
POI	`GET /v1/poi`	Points of Interest
Proximity	`GET /v1/proximity`	Proximity
Static Maps	`GET /v1/staticmaps`	Static Maps
Geoment	`GET /v1/geoment`	Geometry Download
Snap-to-Road	`GET /v1/snaptoroad`	Snap to Road
Geofencing	`GET /v1/geofencing`	Geofencing

Quick Start

Prerequisites

Node.js >= 24.0.0
npm or yarn
Cercalia API Key (Register here)

Installation

# Clone the repository
git clone https://github.com/nexusgeographics/cercalia-openapi.git
cd cercalia-openapi

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Edit .env and add your Cercalia API key
# CERCALIA_API_KEY=your_api_key_here

Running the Application

# Development mode (with hot-reload)
npm run start:dev

# Production mode
npm run build
npm run start:prod

# With Docker
docker-compose up

Access Points

Resource	URL
Swagger UI	http://localhost:3000/api
Health Check	http://localhost:3000/health
API Base URL	http://localhost:3000/v1

Authentication

All API endpoints require the X-API-Key header:

curl -X GET "http://localhost:3000/v1/geocoding?query=Barcelona" \
  -H "X-API-Key: your_api_key"

Example Requests

Geocode an Address

curl -X GET "http://localhost:3000/v1/geocoding?query=Passeig%20de%20Gracia%2092%2C%20Barcelona" \
  -H "X-API-Key: your_api_key"

Calculate a Route

curl -X GET "http://localhost:3000/v1/routing?origin=41.3851,2.1734&destination=41.4036,2.1744" \
  -H "X-API-Key: your_api_key"

Search for Nearby POIs

curl -X GET "http://localhost:3000/v1/proximity/nearest?lat=41.3851&lng=2.1734&categories=gas_station" \
  -H "X-API-Key: your_api_key"

Configuration

Environment Variables

Variable	Description	Default
`PORT`	Server port	`3000`
`CERCALIA_API_KEY`	Your Cercalia API key	Required
`CERCALIA_BASE_URL`	Cercalia API base URL	`https://lb.cercalia.com/services/v2/json`
`CERCALIA_SUGGEST_URL`	Cercalia Suggest service URL	`https://lb.cercalia.com/suggest/SuggestServlet`
`LOG_FORMAT`	Log format (`json` or `text`)	`text`
`DEBUG`	Enable debug logging	`false`
`NODE_ENV`	Environment (`development`, `production`)	`development`

Example `.env` File

# Required
CERCALIA_API_KEY=your_api_key_here

# Optional
CERCALIA_BASE_URL=https://lb.cercalia.com/services/v2/json
CERCALIA_SUGGEST_URL=https://lb.cercalia.com/suggest/SuggestServlet
PORT=3000
LOG_FORMAT=json
DEBUG=false

Docker Deployment

Build and Run

# Build the image
docker build -t cercalia-openapi .

# Run with environment file
docker run -p 3000:3000 --env-file .env cercalia-openapi

Docker Compose

# Production mode
docker-compose up -d

# Development mode (with hot-reload)
docker-compose --profile dev up

# View logs
docker-compose logs -f

Health Checks

The container includes Kubernetes-ready health checks:

Endpoint	Purpose
`GET /v1/health/live`	Liveness probe - Process is running
`GET /v1/health/ready`	Readiness probe - Service is ready (includes backend check)
`GET /v1/health`	Basic health status

Error Handling

All errors follow a consistent JSON format:

{
  "statusCode": 400,
  "message": "Invalid coordinates",
  "error": "Bad Request",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/v1/geocoding",
  "requestId": "abc123-def456"
}

Common Error Codes

Status	Description
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - API key not authorized for this service
`404`	Not Found - No results found
`500`	Internal Server Error
`503`	Service Unavailable - Backend unavailable

Development

Available Scripts

Script	Description
`npm run start:dev`	Start in development mode with hot-reload
`npm run start:prod`	Start in production mode
`npm run build`	Build the application
`npm run test`	Run unit tests
`npm run test:e2e`	Run end-to-end tests
`npm run test:cov`	Run tests with coverage
`npm run lint`	Lint and fix code
`npm run format`	Format code with Prettier
`npm run swagger:generate`	Generate Swagger HTML documentation
`npm run docker:build`	Build Docker image
`npm run type-check`	TypeScript type checking

Generating API Documentation

# Generate static Swagger HTML
npm run swagger:generate

This creates:

docs/swagger/openapi.json - OpenAPI specification
docs/swagger/index.html - Standalone Swagger UI

Resources