Location Services
Geocoding, reverse geocoding, and timezone lookup services.
Overview
Location services help you convert between place names and coordinates, and lookup timezone information for accurate chart calculations.
GET /location/autocomplete
Search for locations by name with autocomplete suggestions.
Query Parameters
query(required): Search string (e.g., "New York")limit(optional): Maximum results (default: 10, max: 50)
Example Request
curl "https://api.astromcp.io/location/autocomplete?query=New%20York&limit=5" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Response
{
success: true;
data: {
query: string;
results: Array<{
name: string;
display_name: string; // Full formatted address
latitude: number;
longitude: number;
country: string;
country_code: string;
state?: string;
city?: string;
timezone: string; // IANA timezone
}>;
count: number;
};
}
Example Response
{
"success": true,
"data": {
"query": "New York",
"results": [
{
"name": "New York",
"display_name": "New York, NY, United States",
"latitude": 40.7128,
"longitude": -74.0060,
"country": "United States",
"country_code": "US",
"state": "New York",
"city": "New York",
"timezone": "America/New_York"
}
],
"count": 1
}
}
GET /location/reverse
Reverse geocode coordinates to get location information.
Query Parameters
lat(required): Latitude (-90 to 90)lng(required): Longitude (-180 to 180)
Example Request
curl "https://api.astromcp.io/location/reverse?lat=40.7128&lng=-74.0060" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Response
{
success: true;
data: {
coordinates: {
latitude: number;
longitude: number;
};
location: {
name: string;
display_name: string;
country: string;
country_code: string;
state?: string;
city?: string;
postal_code?: string;
timezone: string;
};
};
}
GET /location/timezone
Get timezone information for coordinates.
Query Parameters
lat(required): Latitudelng(required): Longitudetimestamp(optional): Unix timestamp for historical timezone data
Example Request
curl "https://api.astromcp.io/location/timezone?lat=40.7128&lng=-74.0060" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Response
{
success: true;
data: {
timezone: string; // IANA timezone (e.g., "America/New_York")
utc_offset: number; // Seconds from UTC
dst_offset: number; // DST offset in seconds
abbreviation: string; // e.g., "EST" or "EDT"
is_dst: boolean; // Currently observing DST?
};
}
POST /location/batch
Lookup multiple locations in a single request.
Request Body
{
locations: Array<{
query?: string; // Name search
coordinates?: { lat: number; lng: number }; // Reverse geocode
}>;
}
Response
Returns array of location results matching the input order.
Use Cases
- Chart input validation: Verify locations exist
- User-friendly input: Allow users to type city names
- Coordinate lookup: Convert addresses to lat/lng
- Timezone determination: Ensure accurate birth time calculations
- Historical charts: Get historical timezone data
Data Sources
Location services use multiple data sources:
- Geocoding: OpenStreetMap Nominatim API
- Timezones: IANA Time Zone Database
- Reverse Geocoding: OpenStreetMap
Rate Limits
- Autocomplete: 60 requests/minute
- Reverse Geocoding: 60 requests/minute
- Batch Requests: 10 requests/minute, max 20 locations per request
Best Practices
- Cache results: Location data rarely changes
- Validate input: Check coordinates are in valid ranges
- Handle DST: Use IANA timezones, not UTC offsets
- Provide context: Show full display names to users
- Batch when possible: Use batch endpoint for multiple lookups
Related Endpoints
- Natal Charts - Requires location data
- Relocation - Compare locations