asterwise-com Utilities API

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'