Tonight's sky for a place

arazzo: 1.0.1
info:
  title: Tonight's sky for a place
  version: 1.0.0
  summary: >-
    Resolve a place name, take the whole-sky snapshot, then find the dark
    moonless observing window for the next week.
sourceDescriptions:
- name: darkWindowApi
  url: ../openapi/cyclecalcs-dark-window-api-openapi.yml
  type: openapi
- name: placesApi
  url: ../openapi/cyclecalcs-places-api-openapi.yml
  type: openapi
- name: todayApi
  url: ../openapi/cyclecalcs-today-api-openapi.yml
  type: openapi
workflows:
- workflowId: tonightsSkyForAPlace
  summary: Place name to a usable observing plan in three keyless GETs.
  inputs:
    type: object
    required: [place]
    properties:
      place:
        type: string
        description: 'City or "City,CC" with an ISO country code, e.g. "Lisbon,PT".'
      nights:
        type: integer
        description: How many nights of dark window to rank (1-62).
  steps:
  - stepId: resolvePlace
    description: Resolve the place name to coordinates and an IANA timezone.
    operationId: getPlaces
    parameters:
    - name: q
      in: query
      value: $inputs.place
    - name: limit
      in: query
      value: 1
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      lat: $response.body#/data/results/0/latitude
      lon: $response.body#/data/results/0/longitude
      tz: $response.body#/data/results/0/timezone
      attribution: $response.body#/attribution
  - stepId: skyToday
    description: One-call whole-sky snapshot for that place, right now.
    operationId: getToday
    parameters:
    - name: lat
      in: query
      value: $steps.resolvePlace.outputs.lat
    - name: lon
      in: query
      value: $steps.resolvePlace.outputs.lon
    - name: tz
      in: query
      value: $steps.resolvePlace.outputs.tz
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      summary: $response.body#/data/summary
  - stepId: darkWindow
    description: The genuinely dark, moonless window per night, ranked.
    operationId: getDarkWindow
    parameters:
    - name: lat
      in: query
      value: $steps.resolvePlace.outputs.lat
    - name: lon
      in: query
      value: $steps.resolvePlace.outputs.lon
    - name: tz
      in: query
      value: $steps.resolvePlace.outputs.tz
    - name: nights
      in: query
      value: $inputs.nights
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      nights: $response.body#/data
  outputs:
    summary: $steps.skyToday.outputs.summary
    darkNights: $steps.darkWindow.outputs.nights
    attribution: $steps.resolvePlace.outputs.attribution
x-generated: '2026-08-09'
x-method: generated
x-note: >-
  Every operationId is verbatim from the harvested OpenAPI. No key is required
  for any step; the free Basic tier serves all three. The `attribution` output
  is carried through deliberately — resolving a place puts a GeoNames CC BY 4.0
  credit obligation on the response.