This guide will help you integrate Cercalia into your application in less than 10 minutes. By the end, you’ll have made your first API call and be ready to build location-aware features.
Prerequisites
Before you begin, ensure you have:
- A Cercalia account (free tier available)
- Basic knowledge of REST APIs or your chosen programming language
- An internet connection
Step 1: Get Your API Key
Create Your Account
Visit the Cercalia Client Portal and register for a free account. You'll receive your API credentials immediately after email verification.
Create Free AccountGenerate API Credentials
After logging in, navigate to API Keys and generate a new key. You'll receive:
API Key— Your unique identifier for authenticationAPI Secret— Keep this secure; never expose it in client-side code
Step 2: Choose Your Integration Method
Cercalia offers multiple ways to integrate our services:
Official SDKs
Pre-built libraries with type safety, error handling, and best practices built-in.
- Python
- TypeScript/JavaScript
- Java
- Go
- Android
- iOS
REST API
Direct HTTP calls to our endpoints. Ideal for custom implementations or unsupported languages.
- Language agnostic
- Full API access
- Postman compatible
OpenAPI Gateway
Proxy with OpenAPI 3.0 specs, Swagger UI, and request validation.
- Auto-generate clients
- Interactive docs
- Request caching
Step 3: Make Your First API Call
Choose your preferred language below and follow the example:
Using Python SDK
# Install the SDK
pip install cercalia
from cercalia import CercaliaClient
# Initialize the client
client = CercaliaClient(api_key="YOUR_API_KEY")
# Geocode an address
result = client.geocoding.search("Passeig de Gràcia 92, Barcelona")
print(f"Coordinates: {result.lat}, {result.lng}")
print(f"Formatted: {result.formatted_address}")
Using TypeScript SDK
# Install the SDK
npm install @cercalia/sdk
import { CercaliaClient } from '@cercalia/sdk';
// Initialize the client
const client = new CercaliaClient({ apiKey: 'YOUR_API_KEY' });
// Geocode an address
const result = await client.geocoding.search('Passeig de Gràcia 92, Barcelona');
console.log(`Coordinates: ${result.lat}, ${result.lng}`);
console.log(`Formatted: ${result.formattedAddress}`);
Using REST API Directly
curl -X GET "https://lb.cercalia.com/services/json?cmd=geocoding&addr=Passeig%20de%20Gracia%2092%2C%20Barcelona" \
-H "Authorization: Bearer YOUR_API_KEY"
Response:
{
"cercalia": {
"cmd": "geocoding",
"version": "1",
"response": {
"candidates": [
{
"id": "1",
"address": {
"country": "ESP",
"city": "Barcelona",
"street": "Passeig de Gràcia",
"number": "92"
},
"coord": {
"x": "2.16127",
"y": "41.39536"
}
}
]
}
}
}
Step 4: Explore More Features
Now that you’ve made your first API call, explore these common use cases:
Calculate a Route
Get driving directions between two points with distance and time estimates.
Routing Guide →Generate Isochrones
Visualize all reachable areas within a time or distance threshold.
Isochrones Guide →Find Points of Interest
Search for restaurants, gas stations, hotels, and millions of other POIs.
POI Guide →Display Interactive Maps
Embed customizable maps in your web application with the JavaScript SDK.
Maps SDK Guide →Common Issues & Troubleshooting
401 Unauthorized Error
This error indicates authentication failure. Check that:
- Your API key is correct and active
- The key hasn't expired
- You're using the correct authentication header format
Rate Limit Exceeded (429)
You've exceeded your plan's request quota. Solutions:
- Implement request caching on your side
- Add retry logic with exponential backoff
- Upgrade to a higher-tier plan
No Results Found
The geocoder couldn't find matches. Try:
- Simplifying the address (remove apartment numbers, etc.)
- Using the
suggestendpoint for autocomplete - Checking for typos in the address