asterwise-com Utilities API
Geocoding and timezone helpers.
Geocoding and timezone helpers.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/asterwise-com:asterwise-com-utilities-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Asterwise Utilities API
description: 'B2B astrology and divination API.
Vedic (sidereal) and Western (tropical) astrology, numerology, tarot, crystals, dreams, and
horoscopes. Send birth data, get accurate calculations as structured JSON. 129 endpoints,
118 MCP tools, HMAC-signed responses.
**Get your free API key** · Pricing · Support
---
## Authentication
Add your API key to every request:
```
Authorization: Bearer YOUR_KEY_HERE
```
Get your key at **asterwise.com** — free, no credit card, instant.
---
## Your first call
```bash
curl https://api.asterwise.com/v1/astro/natal \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d ''{
"name": "Arjun Mehta",
"date": "1985-11-12",
"time": "06:45",
"location": "Mumbai"
}''
```
---
## Key concepts
**`location`** — Any city name. Resolved automatically.
**`ayanamsa`** — `lahiri` (default) · `raman` · `kp` · `tropical`
---
500 free calls/month
status.asterwise.com · Error Reference'
contact:
name: Asterwise
url: https://asterwise.com/
license:
name: Commercial
identifier: LicenseRef-Commercial
version: '2026-03-01'
servers:
- url: https://api.asterwise.com
description: Production
tags:
- name: Utilities
description: Geocoding and timezone helpers.
paths:
/v1/utils/geocode:
get:
tags:
- Utilities
summary: Geocode a Place to Coordinates and Timezone
description: 'Resolve a city or place name to coordinates and timezone.
Returns up to `limit` matches (default 5, at most 10). When a query is ambiguous
(e.g. ''Fatehabad'' exists in multiple states), multiple results
are returned so the developer can present a disambiguation UI
or use the first result. Repeat matches for one place (same city, state
and country within 5 km) are listed once.
Examples: ?q=Mumbai, ?q=Rome Italy, ?q=New York USA, ?q=London UK
Pass state/country for precise results:
?q=Fatehabad,Haryana or ?q=Fatehabad&country=in'
operationId: geocode_v1_utils_geocode_get
parameters:
- name: q
in: query
required: true
schema:
type: string
description: 'City or location name. Use comma for disambiguation: ''Fatehabad,Haryana'''
title: Q
description: 'City or location name. Use comma for disambiguation: ''Fatehabad,Haryana'''
- name: limit
in: query
required: false
schema:
type: integer
maximum: 10
minimum: 1
description: Maximum results to return
default: 5
title: Limit
description: Maximum results to return
- name: country
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: ISO country code to narrow results, e.g. 'in', 'us'
title: Country
description: ISO country code to narrow results, e.g. 'in', 'us'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse_GeocodeResponse_'
'401':
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Authorization failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'413':
description: Payload too large
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'502':
description: Upstream provider error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
description: Service unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- BearerAuth: []
/v1/utils/timezone:
get:
tags:
- Utilities
summary: IANA Timezone for Coordinates
description: 'Returns the IANA timezone (e.g. Asia/Kolkata) for a latitude and longitude pair.
Fully offline — no external API call.
Accepts ?latitude=&longitude= and/or ?lat=&lon= (any pair that supplies both coordinates).
Examples: ?latitude=19.055&longitude=72.869 (Mumbai), ?lat=19.055&lon=72.869'
operationId: timezone_from_coordinates_v1_utils_timezone_get
parameters:
- name: latitude
in: query
required: false
schema:
anyOf:
- type: number
maximum: 90
minimum: -90
- type: 'null'
description: 'Latitude (alias: lat)'
title: Latitude
description: 'Latitude (alias: lat)'
- name: longitude
in: query
required: false
schema:
anyOf:
- type: number
maximum: 180
minimum: -180
- type: 'null'
description: 'Longitude (alias: lon)'
title: Longitude
description: 'Longitude (alias: lon)'
- name: lat
in: query
required: false
schema:
anyOf:
- type: number
maximum: 90
minimum: -90
- type: 'null'
description: Alias for latitude
title: Lat
description: Alias for latitude
- name: lon
in: query
required: false
schema:
anyOf:
- type: number
maximum: 180
minimum: -180
- type: 'null'
description: Alias for longitude
title: Lon
description: Alias for longitude
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ApiResponse_TimezoneResponse_'
'401':
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Authorization failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'413':
description: Payload too large
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'502':
description: Upstream provider error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
description: Service unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- BearerAuth: []
components:
schemas:
GeocodeResult:
properties:
label:
type: string
title: Label
description: Human-readable location label.
city:
anyOf:
- type: string
- type: 'null'
title: City
description: City name.
state:
anyOf:
- type: string
- type: 'null'
title: State
description: State or region.
country:
anyOf:
- type: string
- type: 'null'
title: Country
description: Country name.
latitude:
type: number
title: Latitude
description: Latitude in decimal degrees.
longitude:
type: number
title: Longitude
description: Longitude in decimal degrees.
timezone:
type: string
title: Timezone
description: IANA timezone identifier.
place_id:
type: string
title: Place Id
description: Nominatim place ID.
type: object
required:
- label
- latitude
- longitude
- timezone
- place_id
title: GeocodeResult
ErrorResponse:
properties:
success:
type: boolean
title: Success
description: Always false for error responses.
default: false
examples:
- false
error:
$ref: '#/components/schemas/ErrorCode'
description: Machine-readable error code. Use this for programmatic error handling. See doc_url for the canonical docs page. The full set of codes is the ErrorCode enum in this schema.
examples:
- validation_error
message:
type: string
title: Message
description: Human-readable explanation of what went wrong and how to fix it. Safe to surface in customer-facing UIs.
examples:
- 'Invalid house_system ''foo''. Valid options: equal, koch, placidus, porphyry, whole_sign.'
details:
items: {}
type: array
title: Details
description: Optional structured details. For validation errors, contains per-field error objects. Empty list when there are no structured details.
examples:
- - loc:
- body
- date
msg: Invalid date
retry_after:
anyOf:
- type: integer
- type: 'null'
title: Retry After
description: Seconds to wait before retrying. Present on 429 (rate limit) and 503 (temporary outage) responses. Null when retry is not advised or applicable.
examples:
- 60
doc_url:
type: string
title: Doc Url
description: Canonical documentation URL for this error code. Contains causes, examples, and resolution steps.
examples:
- https://docs.asterwise.com/reference/errors/validation_error/
request_id:
anyOf:
- type: string
- type: 'null'
title: Request Id
description: Unique identifier for this request. Include when contacting support to enable rapid investigation.
examples:
- 3f2b8c1e-7a4d-4e9b-8c21-5d6f0a9b1e37
timestamp:
anyOf:
- type: string
- type: 'null'
title: Timestamp
description: ISO 8601 timestamp of when the error occurred. UTC.
examples:
- '2026-05-19T12:34:56.789Z'
type: object
required:
- error
- message
- doc_url
title: ErrorResponse
description: 'Standard error envelope returned by all Asterwise API endpoints.
Every error response follows this 8-field shape. The ''error'' field
is the machine-readable identifier (use it for programmatic handling).
The ''message'' field is the human-readable explanation. The ''doc_url''
field links to the canonical documentation for the error code.
Include ''request_id'' when contacting support.'
ApiResponse_TimezoneResponse_:
properties:
success:
type: boolean
title: Success
description: True if the request succeeded
default: true
message:
type: string
title: Message
description: Human-readable status message
default: success
data:
$ref: '#/components/schemas/TimezoneResponse'
description: The endpoint response payload
type: object
required:
- data
title: ApiResponse[TimezoneResponse]
ApiResponse_GeocodeResponse_:
properties:
success:
type: boolean
title: Success
description: True if the request succeeded
default: true
message:
type: string
title: Message
description: Human-readable status message
default: success
data:
$ref: '#/components/schemas/GeocodeResponse'
description: The endpoint response payload
type: object
required:
- data
title: ApiResponse[GeocodeResponse]
TimezoneResponse:
properties:
latitude:
type: number
title: Latitude
description: Input latitude.
longitude:
type: number
title: Longitude
description: Input longitude.
timezone:
type: string
title: Timezone
description: IANA timezone identifier.
type: object
required:
- latitude
- longitude
- timezone
title: TimezoneResponse
GeocodeResponse:
properties:
query:
type: string
title: Query
description: The search query as received.
count:
type: integer
title: Count
description: Number of results returned.
ambiguous:
type: boolean
title: Ambiguous
description: True if multiple locations matched the query.
results:
items:
$ref: '#/components/schemas/GeocodeResult'
type: array
title: Results
description: List of matching locations, best match first. Repeat matches for one place (same city, state and country within 5 km) are listed once.
tip:
anyOf:
- type: string
- type: 'null'
title: Tip
description: Disambiguation hint when ambiguous is True.
type: object
required:
- query
- count
- ambiguous
- results
title: GeocodeResponse
ErrorCode:
type: string
enum:
- authentication_failed
- api_key_missing
- api_key_not_found
- api_key_revoked
- api_key_invalid
- session_not_found
- session_revoked
- session_expired
- session_required
- email_not_verified
- ip_rate_limit_exceeded
- login_attempts_exceeded
- account_action_limit_exceeded
- burst_limit_exceeded
- monthly_usage_limit_exceeded
- validation_error
- invalid_email
- invalid_request_body
- sun_calculation_failed
- solar_day_out_of_range
- ephemeris_unavailable
- location_required
- geocode_query_too_short
- plan_not_found
- account_not_found
- key_not_found
- subscription_not_found
- city_not_found
- resource_not_found
- ownership_denied
- payment_verification_failed
- order_creation_failed
- already_on_plan
- max_keys_exceeded
- subscription_expired
- payment_provider_unavailable
- payment_request_invalid
- payload_too_large
- email_delivery_failed
- geocode_unavailable
- internal_error
title: ErrorCode
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: 'Pass your Asterwise API key as a Bearer token. Example: Authorization: Bearer aw_live_xxxx'