Search Terminals
Search for ports, terminals, and intermodal facilities using various search parameters. The API supports text search, filtering by type, location-based search, and pagination.
Endpoint
GET /api/v1/terminals/search
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
query | string | No | Text search query to match against terminal names and details |
type | string | No | Filter by terminal type (e.g., "marine", "rail", "intermodal") |
city | string | No | Filter by city name |
state | string | No | Filter by state code (2-letter code) |
zip | string | No | Filter by ZIP code |
lat | number | No | Latitude for geospatial search (must be used with lng) |
lng | number | No | Longitude for geospatial search (must be used with lat) |
radius | number | No | Search radius in miles for geospatial search (default: 50) |
limit | number | No | Number of results per page (default: 10) |
page | number | No | Page number for pagination (default: 1) |
Example Requests
# Basic text search
curl -X GET 'https://api.drayrates.ai/api/v1/terminals/search?query=port+elizabeth' \
-H 'x-api-key: YOUR_API_KEY'
# Filter by type and city
curl -X GET 'https://api.drayrates.ai/api/v1/terminals/search?type=marine&city=Los+Angeles' \
-H 'x-api-key: YOUR_API_KEY'
# Geospatial search
curl -X GET 'https://api.drayrates.ai/api/v1/terminals/search?lat=33.7490&lng=-84.3880&radius=25' \
-H 'x-api-key: YOUR_API_KEY'
# Pagination example
curl -X GET 'https://api.drayrates.ai/api/v1/terminals/search?limit=20&page=2' \
-H 'x-api-key: YOUR_API_KEY'
Search Behavior
The API implements the following search behaviors:
- Text Search:
- Searches across terminal names, groups, cities, states (including full state names), types, and ZIP codes
- Address field is only included in the search when address-related parameters are provided (city, state, zip, lat, lng)
- Supports prefix matching for better search results
- Prioritizes exact matches
- Location-based Search:
- Supports geospatial search using latitude and longitude coordinates
- Results are sorted by distance from the provided coordinates
- Cannot be combined with city/state/zip filters
- Filtering:
- Multiple filters can be combined using AND logic
- Type filters match exact terminal types
- City filters support partial matches
Response Fields
Field | Type | Description |
---|---|---|
name | string | Terminal name |
geolocation | array | latitude, longitude coordinates |
type | string | Terminal type (marine, rail, intermodal) |
address | string | Street address |
city | string | City name |
state | string | State code (2-letter) |
zip | string | ZIP code |
Response Format
{
"status": "success",
"data": [
{
"name": "APM Elizabeth Terminal",
"geolocation": [40.7128, -74.006],
"type": "marine",
"address": "123 Terminal Way",
"city": "Elizabeth",
"state": "NJ",
"zip": "07201"
}
],
"pagination": {
"currentPage": 1,
"totalPages": 5,
"totalHits": 48,
"hitsPerPage": 10
}
}
Input Validation Rules
The API enforces the following validation rules:
- Geospatial search (lat/lng) cannot be combined with city/state/zip filters
- Latitude must be between -90 and 90
- Longitude must be between -180 and 180
- Radius must be a positive number
- Page number must be a positive integer
- Limit must be a positive integer
Error Responses
Status Code | Description |
---|---|
400 | Bad Request - Missing required search parameters |
400 | Bad Request - Invalid combination of search parameters |
401 | Unauthorized - Missing or invalid API key |
401 | Unauthorized - Missing organization context |
Error Response Examples
Missing Search Parameters
{
"error": {
"code": 400,
"message": "At least one search parameter is required"
}
}
Invalid Parameter Combination
{
"error": {
"code": 400,
"message": "Cannot use city/state/zip filters with geospatial search (lat/lng)"
}
}
Missing Organization Context
{
"error": {
"code": 401,
"message": "Missing organization context"
}
}