Drayrates Logo

Resources
Find what you need here

Terminals API

Search and retrieve information about ports, terminals, and intermodal facilities through our Terminals API endpoints.

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

ParameterTypeRequiredDescription
querystringNoText search query to match against terminal names and details
typestringNoFilter by terminal type (e.g., "marine", "rail", "intermodal")
citystringNoFilter by city name
statestringNoFilter by state code (2-letter code)
zipstringNoFilter by ZIP code
latnumberNoLatitude for geospatial search (must be used with lng)
lngnumberNoLongitude for geospatial search (must be used with lat)
radiusnumberNoSearch radius in miles for geospatial search (default: 50)
limitnumberNoNumber of results per page (default: 10)
pagenumberNoPage 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:

  1. 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
  2. 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
  3. Filtering:
    • Multiple filters can be combined using AND logic
    • Type filters match exact terminal types
    • City filters support partial matches

Response Fields

FieldTypeDescription
namestringTerminal name
geolocationarraylatitude, longitude coordinates
typestringTerminal type (marine, rail, intermodal)
addressstringStreet address
citystringCity name
statestringState code (2-letter)
zipstringZIP 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 CodeDescription
400Bad Request - Missing required search parameters
400Bad Request - Invalid combination of search parameters
401Unauthorized - Missing or invalid API key
401Unauthorized - 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"
  }
}