Go SDK for Cercalia

Idiomatic Go SDK for Cercalia APIs with pkg.go.dev reference and open-source repository.

Cercalia SDK for Go

Official Go SDK for Cercalia APIs. This SDK provides a strongly-typed, idiomatic Go interface to interact with Cercalia’s geospatial services.

Reference: https://pkg.go.dev/github.com/cercalia/cercalia-sdk-go

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

Features

Geocoding: Search for addresses, localities, postal codes, and road milestones.
Reverse Geocoding: Get addresses from coordinates.
Routing: Calculate routes with multiple stops and advanced parameters.
Isochrones: Calculate time or distance-based reachable areas.
Suggest: Get real-time address suggestions.
Geofencing: Perform spatial operations like point-in-polygon.
Static Maps: Generate map images for specific areas or routes.
POI: Search for Points of Interest.
Proximity: Find nearby points or services.
Snap to Road: Align GPS points to the road network.
Geoment: Retrieve administrative geometries (municipalities, postal codes).

Installation

go get github.com/cercalia/cercalia-sdk-go

Quick Start

The SDK can be initialized by providing an API key directly or by setting the CERCALIA_API_KEY environment variable.

Option 1: Environment Variable (Recommended)

export CERCALIA_API_KEY="YOUR_API_KEY"

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/cercalia/cercalia-sdk-go/cercalia"
	"github.com/cercalia/cercalia-sdk-go/cercalia/geocoding"
)

func main() {
	// Initialize client using CERCALIA_API_KEY environment variable
	client := cercalia.NewClient(cercalia.Config{})

	// Use Geocoding service
	service := geocoding.NewService(client)
	ctx := context.Background()

	res, err := service.Geocode(ctx, geocoding.Params{
		Street:   "Diagonal 22",
		Locality: "Barcelona",
	})
	if err != nil {
		log.Fatal(err)
	}

	for _, result := range res {
		fmt.Printf("Found: %s at (%f, %f)\n", 
			result.Name, result.Coord.Lat, result.Coord.Lng)
	}
}

Option 2: Explicit API Key

client := cercalia.NewClient(cercalia.Config{
    APIKey: "YOUR_API_KEY",
})

Documentation

For detailed documentation of each service, see DOCUMENTATION.md or visit pkg.go.dev.

Examples

Check the examples/ directory for complete working examples of every service:

Development

Running Tests

go test ./...

Formatting and Linting

go fmt ./...
go vet ./...

License

This project is licensed under the MIT License - see the LICENSE file for details.