Rails Location API — Rails Cloud

← All APIs · Auth Pay Media Vault Messaging

Base URL

            https://location.railscloud.co/api/v1/atlas
        

Authentication

Include your API key in the Authorization header. Geocoding, routing, and place search endpoints are public (API key only). Address, tracking, and zone management endpoints require a user session token.

# API key authentication (all requests)
Authorization: Bearer dk_live_your_api_key

# User session (addresses, tracking, zone management)
X-Session-Token: usr_session_token_here

How Location Works

Rails Location combines geocoding, routing, and crowd-sourced place data with real-time tracking. Perfect for delivery apps, ride-hailing, logistics, and any location-aware application.

1 Convert addresses to coordinates with POST /geocode

2 Calculate routes and ETAs with POST /routes (driving, walking, transit)

3 Discover nearby places and businesses with GET /places/nearby

4 Track drivers and deliveries in real-time via REST or WebSocket

Quick Start

# Forward geocode: address to coordinates
curl -X POST https://location.railscloud.co/api/v1/atlas/geocode \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"address": "1 First Street, Harare, Zimbabwe"}'

# Response: {"data": {"lat": -17.8292, "lng": 31.0522, "formatted": "...", "confidence": 0.95}}

# Calculate a route
curl -X POST https://location.railscloud.co/api/v1/atlas/routes \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": {"lat": -17.8292, "lng": 31.0522},
    "destination": {"lat": -17.7875, "lng": 31.0447},
    "mode": "driving"
  }'

# Response: {"data": {"distance": "5.2 km", "duration": "12 min", "polyline": "...", ...}}

Endpoints

Geocoding

POST /geocode Convert address to coordinates

POST /reverse-geocode Convert coordinates to address

Routing

POST /routes Calculate route with turn-by-turn directions

POST /distance-matrix Distance and time between multiple points

Places

GET /places/search Search places by query and category

GET /places/nearby Find nearby places by coordinates and radius

GET /places/{id} Get place details

POST /places/contribute Contribute a new place (crowd-sourced)

POST /places/{id}/confirm Confirm an existing place

Zones (Geofencing)

GET /zones List all zones (filter by type/status)

GET /zones/{id} Get zone details and polygon

POST /zones/check Check if point is within any zone

POST /zones Create a zone (polygon boundaries)

PATCH /zones/{id} Update zone name or properties

DELETE /zones/{id} Delete a zone

Addresses

POST /addresses Save a new address

GET /addresses List saved addresses

GET /addresses/{id} Get address details

PATCH /addresses/{id} Update address details

DELETE /addresses/{id} Delete a saved address

POST /addresses/{id}/default Set as default address

Real-Time Tracking

POST /tracking/{entity_type}/{entity_id} Update entity location

GET /tracking/{entity_type}/{entity_id} Get latest location

GET /tracking/{entity_type}/{entity_id}/history Get location history (time range)

GET /tracking/{entity_type}/nearby Find nearby entities within radius

WebSocket (Live Tracking)

WS /ws/tracking/{entity_type}/{entity_id} Stream live location updates

Example: Delivery Zone Check

# Check if a delivery address is within your service area
curl -X POST https://location.railscloud.co/api/v1/atlas/zones/check \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"lat": -17.8292, "lng": 31.0522}'

# Response:
# {"data": {
#   "in_zone": true,
#   "zones": [{
#     "id": "zone_abc", "name": "Harare CBD",
#     "properties": {"delivery_fee": 2.50, "est_delivery": "30 min"}
#   }]
# }}

Example: Track a Driver

# Update driver location (from driver's device)
curl -X POST https://location.railscloud.co/api/v1/atlas/tracking/driver/drv_123 \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "X-Session-Token: DRIVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lat": -17.8310, "lng": 31.0498,
    "speed": 45.2, "heading": 180
  }'

# Find nearby drivers (from customer's app)
curl "https://location.railscloud.co/api/v1/atlas/tracking/driver/nearby?lat=-17.8292&lng=31.0522&radius=5" \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "X-Session-Token: CUSTOMER_TOKEN"

# Response: {"data": [{"entity_id": "drv_123", "distance_km": 1.2, "speed": 45.2, ...}]}

Rate Limits

Geocoding requests 50 per second

Route calculations 20 per second

Location updates 1 per entity per second

General API calls Based on your tier (600–1,000 req/min)

Error Responses

All errors follow a standard format.

{
  "error": "geocode_failed",
  "message": "Unable to geocode the provided address"
}

400 Invalid coordinates or address format

401 Invalid or missing API key / session token

404 Place, zone, or entity not found

422 Invalid polygon or routing parameters

429 Rate limit exceeded

Get Started with Rails Location