openapi: 3.1.0
info:
  title: Popcast Attention
  version: 0.1.0
  description: |
    Popcast Attention will show what is about to draw people to a US Census block group: the upcoming schedule of concerts, sports, conferences, festivals, community events, school sessions and civic or holiday dates, with expected attendance. Look ahead with `horizon`; look back with `window` on the history endpoint.

    **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: attention
    description: Upcoming events and calendar dates for a block group, with expected attendance. Coming soon.
    x-displayName: Attention
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:
    EventItem:
      type: object
      required:
        - id
        - name
        - category
        - start_time
        - source
      properties:
        id:
          type: string
          description: Unique id of the record.
        name:
          type: string
          description: Event name.
        category:
          type: string
          enum:
            - concert
            - sports
            - conference
            - festival
            - community
            - school
            - civic
            - holiday
          description: Kind of event.
        start_time:
          type: string
          format: date-time
          description: When the event starts (ISO 8601).
        end_time:
          type: string
          format: date-time
          description: When the event ends (ISO 8601), when known.
        venue_name:
          type: string
          description: Venue name.
        venue_address:
          type: string
          description: Venue street address.
        latitude:
          type: number
          description: Latitude (WGS84).
        longitude:
          type: number
          description: Longitude (WGS84).
        expected_attendance:
          type: integer
          description: Expected attendance, when known.
        url:
          type: string
          format: uri
          description: Link to the event listing.
        source:
          type: string
          description: Which source supplied this record.
      description: One scheduled event.
    AttentionPayload:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventItem'
          description: The scheduled events, soonest first.
        total_expected_attendance:
          type: integer
          description: Sum of expected attendance across the events.
        categories:
          type: object
          additionalProperties:
            type: integer
          description: Count of items in each category, keyed by category.
        peak_day:
          type: string
          nullable: true
          description: The day with the most expected attendance (`YYYY-MM-DD`), or `null`.
      description: The events ahead and their summary.
    AttentionSignal:
      type: object
      required:
        - fips
        - signal_layer
        - horizon_days
        - period_end
        - refreshed_at
        - payload
      properties:
        fips:
          type: string
          description: 12-digit US Census block group FIPS code.
        signal_layer:
          type: string
          enum:
            - attention
          description: Which signal layer this record belongs to.
        period_end:
          type: string
          description: Last day of the period this record covers (`YYYY-MM-DD`).
        horizon_days:
          type: integer
          enum:
            - 7
            - 14
            - 30
          description: How many days ahead the signal looks.
        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/AttentionPayload'
      description: The forward-looking event 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.
        provenance:
          type: object
          additionalProperties: true
          description: Where the data came from and how mature it is.
      description: Request metadata.
    AttentionSignalResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AttentionSignal'
        meta:
          $ref: '#/components/schemas/Meta'
      description: One attention signal with request metadata.
    AttentionHistorySnapshot:
      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.
        event_count:
          type: integer
          description: Events that took place in the window.
        total_attendance:
          type: integer
          description: Total attendance across those events.
        categories:
          type: object
          additionalProperties:
            type: integer
          description: Count of items in each category, keyed by category.
        data_quality:
          type: string
          description: 'Confidence in the signal: `high`, `medium` or `low`.'
      description: Past event activity rolled up over one window.
    AttentionHistoryResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AttentionHistorySnapshot'
          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.
    AttentionBatchRequest:
      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).
        horizon:
          type: integer
          enum:
            - 7
            - 14
            - 30
          description: Days ahead to include (7, 14 or 30).
      description: Block groups to look up and how far ahead to look.
    AttentionBatchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AttentionSignal'
          description: The list of results.
        meta:
          $ref: '#/components/schemas/Meta'
      description: One attention 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 Attention
    tags:
      - attention
x-customer-voice: true