Java SDK for Cercalia

Production-ready Java SDK for Cercalia APIs with sync/async support, reference documentation, and source code links.

  10 minute read  

Cercalia SDK for Java

Java SDK

A modern, type-safe Java SDK for Cercalia web services. Build powerful location-based applications with geocoding, routing, POI search, and more—with full support for Java 8, 11, 17, and 21.

Reference: https://docs.cercalia.com/docs/sdks/reference/java/

Source code: https://github.com/Cercalia/cercalia-sdk-java

import com.cercalia.sdk.CercaliaConfig;
import com.cercalia.sdk.services.GeocodingService;
import com.cercalia.sdk.services.RoutingService;
import com.cercalia.sdk.model.geocoding.GeocodingCandidate;
import com.cercalia.sdk.model.routing.RouteResult;

CercaliaConfig config = new CercaliaConfig("your-api-key");
GeocodingService geocoding = new GeocodingService(config);

List<GeocodingCandidate> candidates = geocoding.geocode(
    GeocodingOptions.builder()
        .street("Gran Vía")
        .locality("Madrid")
        .build()
);

Table of Contents

About Cercalia

Cercalia is a comprehensive geospatial platform that provides mapping, geocoding, routing, and location intelligence services. Originally developed in Spain, Cercalia offers exceptional coverage of European markets with high-quality cartographic data and advanced spatial analysis capabilities.

This SDK provides a clean, modern interface to Cercalia’s web services, abstracting away the complexity of raw API calls while preserving the full power of the platform.

Features

  • 🎯 Type-Safe: Built with strong typing and null safety annotations
  • ☕ Java 8+ Compatible: Single codebase supporting Java 8, 11, 17, and 21
  • 📦 Modern Architecture: Clean, modular design following best practices
  • 🔄 Comprehensive Services: 11 geospatial services including:
    • Geocoding - Convert addresses to coordinates
    • Reverse Geocoding - Get addresses from coordinates
    • Routing - Calculate optimal routes with turn-by-turn directions
    • Suggest - Autocomplete and place suggestions
    • POI Search - Find points of interest
    • Isochrones - Calculate reachability areas
    • Proximity - Distance calculations and nearest neighbor search
    • Geofencing - Spatial boundary operations
    • Static Maps - Generate map images
    • Snap to Road - Map-match GPS traces to road network
    • Geoment - Geographic element geometry retrieval
  • ⚡ Async Support: Both synchronous and asynchronous APIs (CompletableFuture)
  • 🛡️ Resilient: Built-in retry logic and error handling
  • 📝 Well-Documented: Comprehensive Javadoc and examples
  • 🧪 Tested: 186 tests across all services with high coverage

Requirements

  • Java: 8, 11, 17, or 21
  • Build Tool: Maven 3.6+
  • Dependencies:
    • OkHttp 4.12.0 (HTTP client)
    • Jackson 2.17.0 (JSON processing)
    • JetBrains Annotations 24.1.0 (null safety)

Installation

Maven

Add to your pom.xml:

<dependency>
    <groupId>com.cercalia</groupId>
    <artifactId>cercalia-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

Add to your build.gradle:

implementation 'com.cercalia:cercalia-sdk:1.0.0'

Build from Source

git clone https://github.com/cercalia/cercalia-sdk-java.git
cd cercalia-sdk-java
make build
make install  # Install to local Maven repository

Getting Your API Key

Before using the SDK, you’ll need a Cercalia API key:

  1. Register for a Cercalia account at https://clients.cercalia.com/register
  2. Obtain your API key from your account dashboard
  3. Configure the SDK with your credentials (see Quick Start below)

The API key authenticates your requests and tracks usage against your plan’s quota.

Quick Start

Here’s a simple example to get you started:

import com.cercalia.sdk.CercaliaConfig;
import com.cercalia.sdk.model.common.Coordinate;
import com.cercalia.sdk.model.geocoding.*;
import com.cercalia.sdk.model.routing.*;
import com.cercalia.sdk.services.GeocodingService;
import com.cercalia.sdk.services.RoutingService;

import java.util.List;

public class QuickStart {
    public static void main(String[] args) {
        // Configure the SDK
        CercaliaConfig config = new CercaliaConfig("your-api-key-here");
        
        // Geocode an address
        GeocodingService geocoding = new GeocodingService(config);
        List<GeocodingCandidate> results = geocoding.geocode(
            GeocodingOptions.builder()
                .street("Paseo de la Castellana, 1")
                .locality("Madrid")
                .countryCode("ESP")
                .build()
        );
        
        GeocodingCandidate first = results.get(0);
        System.out.println("Name: " + first.getName());
        System.out.println("Coordinates: " + first.getCoord().getLat() + 
                          ", " + first.getCoord().getLng());
        System.out.println("City: " + first.getCity());
        System.out.println("Region: " + first.getRegion());
        
        // Calculate a route
        RoutingService routing = new RoutingService(config);
        RouteResult route = routing.calculateRoute(
            new Coordinate(40.419838, -3.692580),  // Madrid
            new Coordinate(41.387015, 2.170047)    // Barcelona
        );
        
        System.out.println("Distance: " + String.format("%.2f", route.getDistance() / 1000.0) + " km");
        System.out.println("Duration: " + (route.getDuration() / 60) + " minutes");
    }
}

Async Example

All services support asynchronous operations using CompletableFuture:

import java.util.concurrent.CompletableFuture;

CercaliaConfig config = new CercaliaConfig("your-api-key");
GeocodingService geocoding = new GeocodingService(config);

// Async geocoding
CompletableFuture<List<GeocodingCandidate>> future = geocoding.geocodeAsync(
    GeocodingOptions.builder()
        .street("Gran Vía")
        .locality("Madrid")
        .build()
);

future.thenAccept(results -> {
    System.out.println("Found " + results.size() + " results");
    results.forEach(r -> System.out.println("  - " + r.getName()));
}).exceptionally(error -> {
    System.err.println("Geocoding failed: " + error.getMessage());
    return null;
});

Core Services

Geocoding

Convert addresses and place names into geographic coordinates.

import com.cercalia.sdk.services.GeocodingService;
import com.cercalia.sdk.model.geocoding.*;

GeocodingService geocoding = new GeocodingService(config);

// Basic address geocoding
List<GeocodingCandidate> results = geocoding.geocode(
    GeocodingOptions.builder()
        .street("Calle Alcalá, 42")
        .locality("Madrid")
        .countryCode("ESP")
        .build()
);

GeocodingCandidate result = results.get(0);
System.out.println(result.getName());
// "Calle Alcalá, 42, Madrid"
System.out.println(result.getCoord());
// Coordinate{lat=40.419123, lng=-3.697421}
System.out.println(result.getCity() + " (" + result.getCityId() + ")");
// "Madrid (ESP0058355L)"

// Single string geocoding
List<GeocodingCandidate> simple = geocoding.geocode("Provença 589, Barcelona");

// Geocode with quality filter
List<GeocodingCandidate> precise = geocoding.geocode(
    GeocodingOptions.builder()
        .street("Gran Vía, 1")
        .locality("Madrid")
        .level(GeocodingLevel.STREET)  // Only street-level matches
        .build()
);

// Road milestone geocoding
List<GeocodingCandidate> milestone = geocoding.geocodeRoad(
    "M-45",           // Road name
    12.0,             // Kilometer
    "Madrid",         // Subregion
    "ESP"             // Country code
);

Key Features:

  • Address normalization and standardization
  • Multiple result candidates with quality scoring
  • Support for partial addresses
  • Administrative boundary information (city, region, country)
  • Road milestone geocoding
  • Postal code search

Reverse Geocoding

Get address information from geographic coordinates.

import com.cercalia.sdk.services.ReverseGeocodingService;
import com.cercalia.sdk.model.reversegeocoding.*;
import com.cercalia.sdk.model.common.Coordinate;

ReverseGeocodingService reverseGeocoding = new ReverseGeocodingService(config);

// Get address from coordinates
Coordinate coord = new Coordinate(41.387015, 2.170047);
ReverseGeocodeResult address = reverseGeocoding.reverseGeocode(coord);

System.out.println(address.getName());
// "Plaça Catalunya, Barcelona"
System.out.println(address.getCity());
// "Barcelona"
System.out.println(address.getPostalCode());
// "08002"

// Reverse geocode with options
ReverseGeocodeResult precise = reverseGeocoding.reverseGeocode(
    new Coordinate(40.416775, -3.703790),
    ReverseGeocodeOptions.builder()
        .level(ReverseGeocodeLevel.ADDRESS)
        .radius(100)  // Search within 100 meters
        .build()
);

// Batch reverse geocoding
List<Coordinate> coords = Arrays.asList(
    new Coordinate(41.387015, 2.170047),
    new Coordinate(40.416775, -3.703790)
);
List<ReverseGeocodeResult> addresses = reverseGeocoding.reverseGeocodeBatch(coords);

// Get timezone information
TimezoneResult timezone = reverseGeocoding.getTimezone(
    new Coordinate(52.252025, 20.995254),
    TimezoneOptions.builder()
        .datetime("2019-09-27T14:30:12Z")
        .build()
);
System.out.println("Timezone: " + timezone.getName());
System.out.println("UTC Offset: " + timezone.getUtcTimeOffset() + "ms");

Key Features:

  • Precise address resolution from coordinates
  • Configurable search radius
  • Nearest road/building detection
  • Full administrative hierarchy
  • Timezone information
  • Census section data (Spain)
  • SIGPAC agricultural parcel data (Spain)

Routing

Calculate optimal routes between locations with detailed information.

import com.cercalia.sdk.services.RoutingService;
import com.cercalia.sdk.model.routing.*;
import com.cercalia.sdk.model.common.Coordinate;

RoutingService routing = new RoutingService(config);

// Simple point-to-point route
Coordinate madrid = new Coordinate(40.416775, -3.703790);
Coordinate barcelona = new Coordinate(41.387015, 2.170047);

RouteResult route = routing.calculateRoute(madrid, barcelona);

System.out.println("Distance: " + (route.getDistance() / 1000.0) + " km");
System.out.println("Duration: " + (route.getDuration() / 60) + " minutes");
System.out.println("WKT: " + route.getWkt().substring(0, 100) + "...");

// Route with waypoints
RouteResult multiStop = routing.calculateRoute(
    madrid,
    barcelona,
    RoutingOptions.builder()
        .addWaypoint(new Coordinate(41.6488, -0.8891))  // Zaragoza
        .build()
);

// Route with preferences
RouteResult fastest = routing.calculateRoute(
    madrid,
    barcelona,
    RoutingOptions.builder()
        .vehicleType(VehicleType.CAR)
        .weight(RouteWeight.TIME)
        .avoidTolls(true)
        .build()
);

// Truck routing with restrictions
RouteResult truck = routing.calculateRoute(
    madrid,
    barcelona,
    RoutingOptions.builder()
        .network(RouteNetwork.LOGISTICS)
        .vehicleWeight(40.0)      // tons
        .vehicleHeight(4.5)       // meters
        .vehicleWidth(2.55)       // meters
        .vehicleLength(18.0)      // meters
        .avoidVehicleRestrictions(true)
        .build()
);

// Get distance and time only (faster, no geometry)
RoutingService.DistanceTime dt = routing.getDistanceTime(madrid, barcelona);
System.out.println("Distance: " + dt.getDistance() + "m");
System.out.println("Duration: " + dt.getDuration() + "s");

Key Features:

  • Multiple route optimization strategies (fastest, shortest, money/tolls)
  • Support for waypoints and multi-stop routes
  • Vehicle-specific routing (car, truck, bicycle, pedestrian)
  • Truck restrictions (weight, height, width, length)
  • Avoid tolls, highways, ferries
  • WKT geometry output
  • Distance and time only queries (fast)

Other Available Services

The SDK provides many more specialized services:

SuggestService

Autocomplete and place search suggestions

SuggestService suggest = new SuggestService(config);

List<SuggestResult> suggestions = suggest.find("Provença", "ESP");
for (SuggestResult s : suggestions) {
    System.out.println(s.getDescription());
}

// Search only cities
List<SuggestResult> cities = suggest.searchCities("Barcelona", "ESP");

// Search and geocode in one call
SuggestGeocodeResult result = suggest.findAndGeocode(
    "Paseo de la Castellana 200, Madrid",
    "ESP"
);

PoiService

Search for points of interest

PoiService poi = new PoiService(config);

// Nearest POIs
List<Poi> pois = poi.searchNearest(
    new Coordinate(40.4168, -3.7038),
    PoiNearestOptions.builder()
        .categories(Arrays.asList("C001"))  // Gas stations
        .limit(5)
        .radius(10000)
        .build()
);

// POIs in extent
List<Poi> inExtent = poi.searchInExtent(
    new MapExtent(
        new Coordinate(42.144, -0.415),
        new Coordinate(42.139, -0.408)
    ),
    PoiInExtentOptions.builder()
        .categories(Arrays.asList("D00GAS"))
        .build()
);

// Weather forecast
WeatherForecast weather = poi.getWeatherForecast(
    new Coordinate(41.39818, 2.1490287)
);

IsochroneService

Calculate reachability areas

IsochroneService isochrone = new IsochroneService(config);

// 30-minute drive time isochrone
IsochroneResult area = isochrone.calculate(
    new Coordinate(40.4168, -3.7038),
    IsochroneOptions.builder()
        .weight(IsochroneWeight.TIME)
        .value(30)  // minutes
        .build()
);

System.out.println("Area WKT: " + area.getWkt());

ProximityService

Distance calculations and nearest neighbor search

ProximityService proximity = new ProximityService(config);

List<ProximityItem> nearest = proximity.findNearest(
    new Coordinate(40.4168, -3.7038),
    ProximityOptions.builder()
        .categories(Arrays.asList("C001"))
        .limit(5)
        .build()
);

GeofencingService

Spatial boundary operations

GeofencingService geofencing = new GeofencingService(config);

// Check if point is in circle
GeofenceMatch result = geofencing.checkPoint(
    new Coordinate(41.3851, 2.1734),
    GeofenceOptions.builder()
        .addCircle(
            new Coordinate(41.3851, 2.1734),
            1000  // radius in meters
        )
        .build()
);

System.out.println("Inside: " + result.isInside());

// Check multiple points
List<GeofenceMatch> results = geofencing.check(
    Arrays.asList(
        new Coordinate(41.3851, 2.1734),
        new Coordinate(40.4168, -3.7038)
    ),
    GeofenceOptions.builder()
        .addPolygon("POLYGON((2.1 41.3, 2.2 41.3, 2.2 41.4, 2.1 41.4, 2.1 41.3))")
        .build()
);

SnapToRoadService

Map-match GPS traces to road network

SnapToRoadService snapToRoad = new SnapToRoadService(config);

List<Coordinate> gpsTrace = Arrays.asList(
    new Coordinate(41.3851, 2.1734),
    new Coordinate(41.3852, 2.1735),
    new Coordinate(41.3853, 2.1736)
);

SnapToRoadResult snapped = snapToRoad.snapToRoad(
    gpsTrace,
    SnapToRoadOptions.builder()
        .simplify(10)  // meters
        .build()
);

StaticMapsService

Generate static map images

StaticMapsService staticMaps = new StaticMapsService(config);

// City map
StaticMapResult map = staticMaps.generateCityMap("Barcelona", "ESP", 400, 300);
System.out.println("Image URL: " + map.getImageUrl());

// Map with markers
List<StaticMapMarker> markers = Arrays.asList(
    StaticMapMarker.at(new Coordinate(41.3851, 2.1734), 1),
    StaticMapMarker.at(new Coordinate(41.4034, 2.1741), 2)
);
StaticMapResult markerMap = staticMaps.generateMapWithMarkers(markers, 400, 300);

GeomentService

Geographic element geometry retrieval

GeomentService geoment = new GeomentService(config);

// Get municipality geometry
GeographicElementResult madrid = geoment.getMunicipalityGeometry(
    GeomentMunicipalityOptions.builder()
        .munc("ESP280796")
        .tolerance(0)
        .build()
);

System.out.println("Name: " + madrid.getName());
System.out.println("WKT: " + madrid.getWkt().substring(0, 100) + "...");

See the examples directory for complete, runnable code samples for each service.

Building and Testing

The SDK includes a comprehensive Makefile for common development tasks:

# Build the SDK
make build

# Run all tests (186 tests)
make test

# Run a specific test
make test-single TEST=GeocodingServiceTest

# Run all examples
make examples

# Run a specific example
make example-routing
make example-poi
make example-geocoding

# Create JAR package
make package

# Install to local Maven repository
make install

# Generate Javadoc
make docs

# Clean build artifacts
make clean

# Show all available commands
make help

Running Tests

# All tests
mvn test

# Specific test class
mvn test -Dtest=GeocodingServiceTest

# Specific test method
mvn test -Dtest=GeocodingServiceTest#testBasicGeocoding

Advanced Configuration

Debug Logging

Enable detailed logging to troubleshoot API calls:

import com.cercalia.sdk.util.Logger;

// Enable debug logging globally
Logger.setDebugEnabled(true);

// Now all service calls will log:
// - Request URLs and parameters
// - Response status
// - Error details

Custom Base URL

If you’re using a Cercalia private instance or proxy:

CercaliaConfig config = new CercaliaConfig.Builder()
    .apiKey("your-api-key")
    .baseUrl("https://your-custom-domain.com/cercalia/v2/json")
    .build();

Retry Configuration

Customize retry behavior for individual services:

CercaliaConfig config = new CercaliaConfig.Builder()
    .apiKey("your-api-key")
    .maxRetries(5)
    .retryDelayMs(2000)
    .build();

Error Handling

All services throw CercaliaException for API errors:

import com.cercalia.sdk.exception.CercaliaException;

try {
    List<GeocodingCandidate> results = geocoding.geocode("Invalid Address");
} catch (CercaliaException e) {
    System.err.println("Geocoding failed: " + e.getMessage());
    System.err.println("Error code: " + e.getErrorCode());
    
    // Handle specific error codes
    if (e.getErrorCode() == 40001) {
        System.err.println("Invalid API key");
    } else if (e.getErrorCode() == 40003) {
        System.err.println("API quota exceeded");
    }
}

Thread Safety

All service classes are thread-safe and can be shared across threads:

// Create once, use everywhere
private static final GeocodingService GEOCODING = 
    new GeocodingService(new CercaliaConfig("your-api-key"));

// Safe to call from multiple threads
public void someMethod() {
    List<GeocodingCandidate> results = GEOCODING.geocode("Barcelona");
}

Examples

The SDK includes comprehensive examples for all services:

Located in examples/src/main/java/com/cercalia/examples/:

Run the examples:

# All examples
make examples

# Specific examples
make example-geocoding
make example-routing
make example-poi

# Or using Maven directly
cd examples
mvn compile exec:java -Dexec.mainClass="com.cercalia.examples.RoutingExample"

Documentation

Official Cercalia Documentation

For detailed API reference, advanced features, and service-specific parameters, visit the official Cercalia documentation:

https://docs.cercalia.com/docs/

The official docs cover:

  • Complete API reference for all services
  • Advanced parameters and options
  • Response format specifications
  • Rate limits and quotas
  • Best practices and optimization tips
  • Regional coverage details

SDK Documentation

  • Javadoc: Generate with make docs or mvn javadoc:javadoc
  • Source Code: All services include comprehensive Javadoc comments
  • Tests: The test suite provides additional usage examples and edge cases
  • Examples: 12 example programs demonstrating all services

Getting Help

  1. Check the examples - Most common use cases are covered
  2. Read the official docs - https://docs.cercalia.com/docs/
  3. Review Javadoc - Generated documentation in target/apidocs/
  4. Open an issue - For SDK-specific bugs or feature requests

License

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

For questions about licensing, contact Cercalia.

Built with Java | Powered by Cercalia | Documentation | Get API Key

Last modified January 16, 2026: feat: improve openapi sections (a7ca4f1)