openapi: 3.1.0
info:
  title: Popcast Ambient
  version: 0.1.0
  description: |
    Popcast Ambient will describe the conditions around a US Census block group right now: the weather with a short forecast, air quality, daylight, a mobility index relative to the block group's own norm, and calendar context such as holidays and school days, refreshed hourly.

    **Coming soon.** This capability is on the Motionworks roadmap and is not yet available to call. The request and response shapes are published so you can plan an integration; they may change before launch.
  contact:
    name: Motionworks AI
    url: https://mworks.com
    email: api@mworks.com
servers:
  - url: https://api2.mworks.com
tags:
  - name: ambient
    description: |
      Current environmental context for a block group — weather, air quality, daylight, mobility and calendar. Coming soon.
    x-displayName: Ambient
paths: {}
components:
  parameters:
    FipsParam:
      name: fips
      in: path
      required: true
      schema:
        type: string
        pattern: ^\d{12}$
      description: 12-digit US Census block group FIPS code.
  schemas:
    WeatherForecastDay:
      type: object
      properties:
        date:
          type: string
          description: Forecast date (`YYYY-MM-DD`).
        high_f:
          type: number
          description: Forecast high, °F.
        low_f:
          type: number
          description: Forecast low, °F.
        condition:
          type: string
          enum:
            - clear
            - partly-cloudy
            - cloudy
            - rain
            - thunderstorm
            - snow
            - fog
            - windy
            - haze
            - unknown
          description: Expected conditions for the day.
        precipitation_chance_pct:
          type: number
          description: Chance of precipitation, as a percentage.
      description: One day of the forecast.
    WeatherSnapshot:
      type: object
      properties:
        current_temp_f:
          type: number
          description: Current temperature, °F.
        condition:
          type: string
          description: Current conditions, as a short label.
        humidity_pct:
          type: number
          description: Relative humidity, as a percentage.
        wind_mph:
          type: number
          description: Wind speed, mph.
        forecast:
          type: array
          items:
            $ref: '#/components/schemas/WeatherForecastDay'
          description: The next few days, one entry per day.
        source:
          type: string
          description: Which source supplied this record.
      description: Current weather and a short forecast.
    AirQualitySnapshot:
      type: object
      properties:
        aqi:
          type: integer
          description: Air Quality Index value.
        category:
          type: string
          enum:
            - good
            - moderate
            - unhealthy-sensitive
            - unhealthy
            - very-unhealthy
            - hazardous
          description: AQI category, from `good` to `hazardous`.
        pm25_ugm3:
          type: number
          nullable: true
          description: Fine particulate (PM2.5) concentration in µg/m³, or `null` when not measured.
        pm10_ugm3:
          type: number
          nullable: true
          description: Coarse particulate (PM10) concentration in µg/m³, or `null` when not measured.
        dominant_pollutant:
          type: string
          nullable: true
          description: The pollutant driving the AQI, or `null`.
        source:
          type: string
          description: Which source supplied this record.
      description: Current air quality.
    DaylightSnapshot:
      type: object
      properties:
        date:
          type: string
          description: The day these times describe (`YYYY-MM-DD`).
        sunrise_local:
          type: string
          description: Sunrise, local time.
        sunset_local:
          type: string
          description: Sunset, local time.
        solar_noon_local:
          type: string
          description: Solar noon, local time.
        daylight_minutes:
          type: integer
          description: Minutes of daylight.
        timezone:
          type: string
          description: IANA time zone of the block group.
      description: Daylight times for the day, in local time.
    MobilitySnapshot:
      type: object
      description: |
        Movement around the block group relative to its own history. Indexes run 0–500, where 100 equals the block group's historical average.
      properties:
        pedestrian_index:
          type: number
          description: Pedestrian activity relative to the block group's norm (100 = average).
        vehicular_index:
          type: number
          description: Vehicle activity relative to the block group's norm (100 = average).
        dwell_index:
          type: number
          description: Time spent in the block group relative to its norm (100 = average).
        inbound_flow_index:
          type: number
          description: Arrivals relative to the block group's norm (100 = average).
        outbound_flow_index:
          type: number
          description: Departures relative to the block group's norm (100 = average).
        sample_size:
          type: integer
          description: Number of observations behind the indexes.
        source:
          type: string
          description: Which source supplied this record.
    CalendarContext:
      type: object
      properties:
        is_federal_holiday:
          type: boolean
          description: Whether the day is a US federal holiday.
        federal_holiday_name:
          type: string
          nullable: true
          description: Name of the holiday, or `null`.
        is_school_day:
          type: boolean
          description: Whether local schools are in session.
        school_district_name:
          type: string
          nullable: true
          description: The school district consulted, or `null`.
        is_weekend:
          type: boolean
          description: Whether the day is a Saturday or Sunday.
        day_of_week:
          type: string
          enum:
            - mon
            - tue
            - wed
            - thu
            - fri
            - sat
            - sun
          description: Day of the week, abbreviated.
      description: Calendar context for the day.
    AmbientPayload:
      type: object
      properties:
        weather:
          $ref: '#/components/schemas/WeatherSnapshot'
        air_quality:
          $ref: '#/components/schemas/AirQualitySnapshot'
        daylight:
          $ref: '#/components/schemas/DaylightSnapshot'
        mobility:
          $ref: '#/components/schemas/MobilitySnapshot'
        calendar:
          $ref: '#/components/schemas/CalendarContext'
      description: The five parts of the ambient signal.
    AmbientSignal:
      type: object
      required:
        - fips
        - signal_layer
        - period_end
        - refreshed_at
        - payload
      properties:
        fips:
          type: string
          description: 12-digit US Census block group FIPS code.
        signal_layer:
          type: string
          enum:
            - ambient
          description: Which signal layer this record belongs to.
        period_end:
          type: string
          description: Last day of the period this record covers (`YYYY-MM-DD`).
        refreshed_at:
          type: string
          format: date-time
          description: When the signal was last refreshed (ISO 8601).
        data_quality:
          type: string
          enum:
            - high
            - medium
            - low
          description: 'Confidence in the signal: `high`, `medium` or `low`.'
        source_breakdown:
          type: object
          additionalProperties:
            type: integer
          description: How many records each contributing source supplied, keyed by source.
        payload:
          $ref: '#/components/schemas/AmbientPayload'
      description: The current ambient signal for one block group.
    Meta:
      type: object
      properties:
        request_id:
          type: string
          description: Unique id for this request. Quote it when contacting support.
        credits_used:
          type: integer
          description: Credits charged for this call.
        product:
          type: string
          description: The Motionworks product that served the call.
        version:
          type: string
          description: API version that served the call.
      description: Request metadata.
    AmbientSignalResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AmbientSignal'
        meta:
          $ref: '#/components/schemas/Meta'
      description: One ambient signal with request metadata.
    AmbientHistorySnapshot:
      type: object
      properties:
        fips:
          type: string
          description: 12-digit US Census block group FIPS code.
        period_start:
          type: string
          description: First day of the period this record covers (`YYYY-MM-DD`).
        period_end:
          type: string
          description: Last day of the period this record covers (`YYYY-MM-DD`).
        window_days:
          type: integer
          description: Length of the rolling window, in days.
        avg_temp_f:
          type: number
          description: Average temperature over the window, °F.
        avg_aqi:
          type: integer
          description: Average Air Quality Index over the window.
        rainy_days:
          type: integer
          description: Days with rain in the window.
        avg_pedestrian_index:
          type: number
          description: Average pedestrian index over the window.
        avg_vehicular_index:
          type: number
          description: Average vehicle index over the window.
        data_quality:
          type: string
          description: 'Confidence in the signal: `high`, `medium` or `low`.'
      description: Ambient conditions rolled up over one window.
    AmbientHistoryResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AmbientHistorySnapshot'
          description: The list of results.
        pagination:
          type: object
          properties:
            cursor:
              type: string
              nullable: true
              description: Opaque cursor for the next page. Pass it back as `cursor` to continue; absent on the last page.
            has_more:
              type: boolean
              description: Whether another page follows.
            total:
              type: integer
              description: Total number of items in the window.
          description: Paging information for the list.
        meta:
          $ref: '#/components/schemas/Meta'
      description: A page of history rollups with request metadata.
    AmbientBatchRequest:
      type: object
      required:
        - fips_codes
      properties:
        fips_codes:
          type: array
          maxItems: 100
          items:
            type: string
            pattern: ^\d{12}$
          description: Block group FIPS codes to look up (12 digits each).
      description: Block groups to look up.
    AmbientBatchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AmbientSignal'
          description: The list of results.
        meta:
          $ref: '#/components/schemas/Meta'
      description: One ambient signal per requested block group, with request metadata.
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Stable machine-readable error code.
            message:
              type: string
              description: Human-readable explanation of the error.
            status:
              type: integer
              description: HTTP status code, repeated in the body.
            request_id:
              type: string
              description: Unique id for this request. Quote it when contacting support.
          description: 'The error: a stable `code`, a human-readable `message`, and the HTTP `status`.'
      description: The standard error envelope.
  responses:
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
x-tagGroups:
  - name: Popcast Ambient
    tags:
      - ambient
x-customer-voice: true
