Skip to main content
The Geocoding API provides powerful location-based services including address geocoding, reverse geocoding, and airport code lookups. It integrates with Google Maps Geocoding API and includes a comprehensive airport database for quick lookups.

​
Features

  • Address Geocoding: Convert addresses into geographic coordinates
  • Airport Code Lookup: Find airport locations by IATA or ICAO codes
  • Structured Responses: Consistent response format with detailed location information
  • Global Coverage: Supports locations worldwide

​
Authentication

All requests must include a valid JWT token in the Authorization header: 
Authorization: Bearer YOUR_JWT_TOKEN

​
Request

​
Path Parameters

ParameterTypeRequiredDescription
addressstringYesThe address or location to geocode (e.g., “1600 Amphitheatre Parkway, Mountain View, CA” or “JFK”)

​
Response

​
200 OK - Successful geocoding

{
  "message": "",
  "data": {
    "address": {
      "city": "Mountain View",
      "state": "California",
      "country": "US",
      "lat": 37.4223878,
      "long": -122.0841877
    }
  }
}

​
200 OK - Airport Code Lookup

{
  "message": "",
  "data": {
    "address": {
      "city": "New York",
      "state": "New York",
      "country": "US",
      "lat": 40.6413111,
      "long": -73.7781391
    }
  }
}

​
400 Bad Request - Invalid Input

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Address parameter is required"
  }
}

​
401 Unauthorized

{
  "error": {
    "code": "AUTH_ERROR",
    "message": "Invalid or missing authentication token"
  }
}

​
404 Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "No results found for the specified address"
  }
}

​
429 Too Many Requests

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later."
  }
}

​
500 Internal Server Error

{
  "error": {
    "code": "SERVER_ERROR",
    "message": "An unexpected error occurred"
  }
}

​
Endpoints

​
Geocode an Address

Converts a human-readable address into geographic coordinates and structured location data. 
GET /geo-locations/address/{address}

​
Examples

​
Geocoding an Address

curl -X GET \
  'https://api-v1.compass.com/geo-locations/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN'

​
Looking up an Airport by Code

curl -X GET \
  'https://api-v1.compass.com/geo-locations/address/JFK' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN'

​
Response Format

All successful responses follow this structure:
FieldTypeDescription
messagestringStatus message (empty if successful)
dataobjectResponse data
- addressobjectLocation information
- citystringCity name
- statestringState or region name
- countrystringTwo-letter country code
- latnumberLatitude coordinate
- longnumberLongitude coordinate

​
Error Handling

Errors follow a standard format: 
{
  "message": "Error message",
  "error": {
    "status": 400,
    "errorMessage": "Detailed error message"
  }
}

​
Common Status Codes

Status CodeDescription
200Success
400Bad Request - Invalid input
401Unauthorized - Invalid token
404Not Found - Address not found
500Internal Server Error

​
Rate Limiting

The API is rate limited to protect service quality. If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

​
Best Practices

  1. Cache results when possible to reduce API calls
  2. Handle errors gracefully and implement retry logic for transient failures
  3. Validate addresses before sending them to the API
  4. Use HTTPS for all requests to ensure data security

​
Integration Example

async function geocodeAddress(address) {
  try {
    const response = await fetch(
      `https://your-api-domain.com/geo-locations/address/${encodeURIComponent(address)}`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_JWT_TOKEN'
        }
      }
    );
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const data = await response.json();
    return data.data.address;
  } catch (error) {
    console.error('Geocoding error:', error);
    throw error;
  }
}

// Example usage
geocodeAddress('JFK')
  .then(location => console.log('Airport location:', location))
  .catch(console.error);

​
Support

For questions or issues, please contact [email protected].