Stream Positions

POST

/stream/positions

request.sh

curl -X POST https://api.astroway.info/v1/stream/positions \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{}'

▸ Try it POST /stream/positions

• Production

Current planetary positions snapshot, tickSeconds=30.

Authorizations

• ApiKeyAuth

Parameters

Query Parameters

fields

string

Comma-separated dotted paths, relative to data, to keep in the response. A path is applied to every element of an array, so planets.name means the name of each planet. Paths that match nothing come back in _fields_unmatched; a list where nothing matches at all is a 400, because an empty object would be a confident wrong answer.

Example

planets.name,planets.longitude

precision

integer

<= 15

Round every non-integer number in the response to this many decimal places. Integers are left alone, because an id is not a measurement. Ecliptic longitudes ship with fourteen decimals by default; 2 is about a tenth of an arcminute.

Example

4

Header Parameters

Idempotency-Key

string

>= 1 characters <= 255 characters /^[\x21-\x7E]+$/

Unique per logical operation, kept across retries. For 24 hours from the first request, a repeat with the same key, method, path, body and query string returns the stored response with Idempotent-Replayed: true and costs 0 credits. The same key with a different body or query string is a 409 IDEMPOTENCY_KEY_REUSED; a repeat while the first is still running is a 409 IDEMPOTENCY_IN_PROGRESS. Only 2xx responses are kept. See /idempotency/.

Example

01HXY2A7ZM0ABCDEF

Request Body ^required

Media type application/json

object

Example

{}

Responses

200

Successful calculation

Media type application/json

object

ok

boolean

data

object

timestamp

string

nullable

julianDay

number

nullable

planets

Array<object>

nullable

object

id

number

nullable

name

string

nullable

longitude

number

nullable

latitude

number

nullable

speed

number

nullable

retrograde

boolean

nullable

sign

string

nullable

degreeInSign

number

nullable

tickSeconds

number

nullable

transport

string

nullable

sseUpgrade

string

nullable

pricing

string

nullable

Example

{
  "ok": true,
  "data": {
    "timestamp": "2026-08-23T22:05:26.767Z",
    "julianDay": 2461276.4204398147,
    "planets": [
      {
        "id": 0,
        "name": "Sun",
        "longitude": 150.79404299195198,
        "latitude": -0.00008204620288850356,
        "speed": 0.9637343842987806,
        "retrograde": false,
        "sign": "Virgo",
        "degreeInSign": 0.7940429919519545
      }
    ],
    "tickSeconds": 30,
    "transport": "http-polling",
    "sseUpgrade": "Use the same endpoint with /sse subpath for Server-Sent Events (planned).",
    "pricing": "10 credits/call (Tier 1): each tick recomputes positions, so it is a live compute, not a cheap lookup. Poll on the returned `tickSeconds`; see docs/PRICING.md §11."
  }
}

400

Validation error

Media type application/json

Example

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Validation failed: date: Date must be YYYY-MM-DD",
    "details": [
      {
        "path": "date",
        "message": "Date must be YYYY-MM-DD"
      }
    ]
  }
}

401

Missing or invalid API key

Media type application/json

Example

{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}