Solvice Maps: API Services Guide
API Architecture Overview
Solvice Maps provides a comprehensive suite of RESTful APIs designed for high-performance routing, distance calculations, and geospatial analysis. The API architecture is built around three core service categories, each optimized for specific use cases and performance requirements.Base URL and Authentication
Production API Base URL:https://routing.solvice.io
Staging API Base URL:https://mapr-gateway-staging-181354976021.europe-west1.run.app
Authentication:
All API requests require authentication via API key in the header:
Core API Services
1. Route API - Turn-by-Turn Directions
Purpose: Generate detailed turn-by-turn directions with geometry between two or more points.Single Route Calculation
Endpoint:POST /route
Request Body:
Batch Route Processing
Endpoint:POST /route/batch
Request Body:
2. Table API - Distance Matrix
Purpose: Calculate travel times and distances between multiple origins and destinations.Synchronous Table (Real-time)
Endpoint:POST /table/sync
Use Case: Small matrices requiring immediate response (< 1000 coordinate pairs)
Request Body:
Asynchronous Table (Large datasets)
Endpoint:POST /table
Use Case: Large matrices requiring background processing (> 1000 coordinate pairs)
Request Body:
Monitor Table Progress
Endpoint:GET /table/{id}/progress
Response:
Retrieve Table Results
Endpoint:GET /table/{id}/response
Response: Same format as synchronous table response, but potentially much larger.
For very large responses (> 10MB):
Endpoint: GET /table/{id}/response/signed-url
Response:
3. Cube API - Time-Dependent Travel Matrix
Purpose: Generate travel time matrices across multiple time periods throughout the day.Create Cube Request
Endpoint:POST /cube
Request Body:
Monitor Cube Progress
Endpoint:GET /cube/{id}/progress
Response:
Retrieve Cube Results
Endpoint:GET /cube/{id}/response
Response:
Advanced Features
1. Request Splitting and Optimization
Automatic Request Splitting: The API automatically splits large requests that exceed routing engine limits:- OSRM: 1000 coordinates per request
- TomTom: 1000 coordinates per request
- AnyMap: 100 coordinates per request
- Google Maps: 1000 coordinates per request
2. Content-Based Caching
Cache Key Generation: The system generates cache keys based on request content, enabling efficient deduplication:- Immediate response for duplicate requests (< 10ms)
- 60-80% cache hit rate for typical workloads
- Significant cost reduction for repeated calculations
3. Multi-Engine Support
Engine Selection:osm
: OpenStreetMap/OSRM (free, good coverage)tomtom
: TomTom API (commercial, real-time traffic)anymap
: AnyMap service (European focus)google
: Google Maps API (premium coverage)
4. Time-Dependent Routing
Traffic Slice Selection:Error Handling
Standard Error Response Format
Common Error Codes
Authentication Errors:INVALID_API_KEY
: API key is missing or invalidRATE_LIMIT_EXCEEDED
: Request rate limit exceededQUOTA_EXCEEDED
: Monthly quota exceeded
INVALID_REQUEST
: Malformed request bodyINVALID_COORDINATES
: Invalid coordinate format or unreachable locationsREQUEST_TOO_LARGE
: Request exceeds maximum size limitsINVALID_PROFILE
: Unsupported transportation profile
ROUTING_ENGINE_ERROR
: External routing engine failureTIMEOUT
: Request processing timeoutINTERNAL_ERROR
: Unexpected server error
RESOURCE_NOT_FOUND
: Requested table/cube ID not foundRESOURCE_EXPIRED
: Results have expired and been deleted
Retry Logic
Recommended Retry Strategy:Rate Limits and Quotas
Request Rate Limits
Standard Limits:- Authenticated requests: 1000 requests/minute
- Table requests: 100 requests/minute
- Cube requests: 10 requests/minute
- Custom rate limits: Configurable per customer
- Burst allowance: Handle traffic spikes
- Priority queues: Faster processing for enterprise customers
Usage Quotas
Monthly Quotas:- Route calculations: Unlimited for standard plans
- Table requests: Based on coordinate combinations
- Storage: 30-day retention for results
Performance Optimization
Request Optimization Tips
-
Batch Similar Requests:
-
Use Appropriate Endpoints:
- Small tables (< 100 coords): Use
/table/sync
- Large tables (> 1000 coords): Use
/table
(async) - Time analysis: Use
/cube
for multiple time periods
- Small tables (< 100 coords): Use
-
Leverage Caching:
-
Choose Optimal Engines:
- Development/Testing: Use
osm
(free) - Production (Europe): Use
anymap
for best accuracy - Global Coverage: Use
google
ortomtom
- Real-time Traffic: Use
tomtom
orgoogle
- Development/Testing: Use
Response Size Optimization
Large Response Handling:- Responses > 10MB automatically use signed URLs
- Use compression for data transfer
- Consider pagination for very large datasets