Discover Yourself for developers

One API for deeper self-discovery.

Add natal charts, numerology, destiny matrices, astrocartography, and live transits to your product through a secure, versioned JSON API.

View quickstart Create free account

Versioned

Stable /v1 contracts

Secure

Scoped, revocable keys

Observable

Request IDs and quotas

POST/v1/birth-charts

Birth charts

Calculate exact planet degrees and arcminutes, display-ready positions, houses, angles, aspects, and authoritative direct/retrograde motion, plus the lunar nodes, Part of Fortune, Lilith and the Vertex.

Required scope: birth-charts:calculate

curl -X POST https://www.discover-yourself.app/v1/birth-charts \
  -H "Authorization: Bearer dy_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "birthDate": "1990-07-15",
  "birthTime": "14:30",
  "lat": 40.7128,
  "lng": -74.006,
  "timezone": -4,
  "timeUnknown": false
}'

Example response — planet placement

{
  "object": "birth_chart",
  "data": {
    "planets": [
      {
        "name": "Mercury",
        "symbol": "☿",
        "longitude": 131.3354,
        "sign": "Leo",
        "signSymbol": "♌",
        "degInSign": 11.3354,
        "degree": 11,
        "minute": 20,
        "position": "11°20′ Leo",
        "house": 9,
        "retrograde": false,
        "motion": "direct",
        "notation": ""
      }
    ],
    "points": [
      {
        "name": "Part of Fortune",
        "symbol": "⊗",
        "kind": "lot",
        "method": "day",
        "longitude": 131.012,
        "sign": "Leo",
        "signSymbol": "♌",
        "element": "Fire",
        "degInSign": 11.012,
        "degree": 11,
        "minute": 0,
        "position": "11°00′ Leo",
        "house": 9,
        "approximate": false
      }
    ],
    "pointAspects": [
      {
        "planet": "Mercury",
        "point": "South Node",
        "aspect": "Conjunction",
        "angle": 0,
        "orb": 0.81
      }
    ]
  },
  "calculation": {
    "engine_version": "1.2.0",
    "zodiac": "tropical",
    "house_system": "placidus",
    "node_type": "mean",
    "lot_formula": "sect"
  }
}

Planet position contract

One calculation, presentation-ready fields

longitude

Absolute 0–360° tropical ecliptic longitude used by the wheel and aspect engine.

degInSign

High-precision decimal position from 0 up to 30 within the named sign.

degree + minute

Normalized components for custom interfaces; one degree contains 60 arcminutes.

position

Ready-to-display value such as 11°20′ Leo.

retrograde + motion

Boolean and readable direct/retrograde status from geocentric motion.

notation

Returns ℞ for retrograde placements and an empty string for direct motion.

Existing longitude, degInSign, and retrograde fields remain available, so this is backward compatible for current v1 clients.

New in engine 1.2.0: birth charts add points (North Node, South Node, Part of Fortune, Lilith and the Vertex, with the same position fields and a method) and pointAspects (planets within 3°). Send timeUnknown: true when the birth time is a guess, and Part of Fortune and the Vertex come back with approximate: true and no house. planets still has exactly 10 items.

Authentication

Send your key in the Authorization header as a Bearer token. Never expose a live key in browser or mobile client code; requests should originate from your backend.

Free limits and errors

Each key includes 10,000 monthly units and a 60-request-per-minute burst limit. Numerology and Destiny Matrix cost 1 unit, charts 2, astrocartography and transits 5. Responses include quota headers, a request ID, and structured validation errors.