Geocoding and geofencing

Geocoding, reverse-geocoding, and geofencing radius checks via @alpha-explora/apicenter-contracts.

The Geo Shared Service provides forward geocoding, reverse geocoding, and geofence boundary checks with cached Google Maps integration and local fallback.

For a Node.js backend, use the typed api.geo methods from the APICenter SDK. The REST reference below documents the same API for other runtimes.

Service Specifications

Base Route: /api/v1/shared/geo
Required Header: Authorization: Bearer <SERVICE_ACCESS_TOKEN>

1. Geocode Address

Endpoint: POST /api/v1/shared/geo/geocode

Request Body (`GeocodeRequest`)

{
  "address": "Ayala Center, Makati City, Philippines",
  "language": "en",
  "region": "ph"
}

Response (`GeocodeResponse`) — `200 OK`

{
  "success": true,
  "data": {
    "formattedAddress": "Ayala Center, Makati, Metro Manila, Philippines",
    "latitude": 14.5519,
    "longitude": 121.0253,
    "placeId": "ChIJb_2y",
    "types": ["establishment", "point_of_interest"],
    "provider": "google-maps",
    "cacheStatus": "hit"
  }
}

2. Reverse Geocode Coordinates

Endpoint: POST /api/v1/shared/geo/reverse-geocode

Request Body (`ReverseGeocodeRequest`)

{
  "latitude": 14.5995,
  "longitude": 120.9842,
  "language": "en"
}

Response — `200 OK`

{
  "success": true,
  "data": {
    "formattedAddress": "Manila, Philippines",
    "latitude": 14.5995,
    "longitude": 120.9842,
    "placeId": "ChIJv0k",
    "types": ["locality", "political"],
    "provider": "google-maps",
    "cacheStatus": "hit"
  }
}

3. Check Geofence Boundaries

Endpoint: POST /api/v1/shared/geo/geofence/check

Request Body

{
  "latitude": 14.5995,
  "longitude": 120.9842,
  "fenceId": "metro-manila"
}

Response — `200 OK`

{
  "success": true,
  "data": {
    "inside": true,
    "distanceDetails": [
      {
        "fenceId": "metro-manila",
        "name": "Metro Manila",
        "inside": true,
        "distanceMeters": 0,
        "radiusMeters": 50000
      }
    ],
    "provider": "local"
  }
}

On this page