openapi: 3.1.0
info:
  title: Popcast Change
  version: 0.1.0
  description: |
    Popcast Change will measure how fast the physical fabric of a US Census block group is changing: building permits, businesses opening and closing, and real-estate activity, rolled up over a window you choose and summarized as a single change-velocity score.

    **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: change
    description: |
      Permits, business openings and closings, and real-estate activity for a block group, with a change-velocity score. Coming soon.
    x-displayName: Change
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:
    PermitEvent:
      type: object
      properties:
        id:
          type: string
          description: Unique id of the record.
        permit_type:
          type: string
          enum:
            - new-construction
            - addition
            - renovation
            - demolition
            - signage
            - electrical
            - plumbing
            - mechanical
            - other
          description: Kind of permit.
        description:
          type: string
          description: Permit description as filed.
        issue_date:
          type: string
          description: When the permit was issued (`YYYY-MM-DD`).
        estimated_value_usd:
          type: number
          description: Estimated construction value, USD.
        latitude:
          type: number
          description: Latitude (WGS84).
        longitude:
          type: number
          description: Longitude (WGS84).
        address:
          type: string
          description: Street address of the permitted work.
        source:
          type: string
          description: Which source supplied this record.
      description: One building permit.
    BusinessEvent:
      type: object
      properties:
        id:
          type: string
          description: Unique id of the record.
        change_type:
          type: string
          enum:
            - new-open
            - closed
            - renovation
            - ownership-transfer
            - rebranding
          description: Kind of change.
        business_name:
          type: string
          description: Name of the business.
        effective_date:
          type: string
          description: When the change took effect (`YYYY-MM-DD`).
        source:
          type: string
          description: Which source supplied this record.
      description: One business opening, closing or change.
    RealEstateSnapshot:
      type: object
      properties:
        active_listings:
          type: integer
          description: Listings currently active.
        median_list_price_usd:
          type: number
          nullable: true
          description: Median list price, USD, or `null`.
        median_days_on_market:
          type: number
          nullable: true
          description: Median days on market, or `null`.
        price_trend_30d_pct:
          type: number
          nullable: true
          description: Change in median list price over the last 30 days, as a percentage, or `null`.
        new_listings_window:
          type: integer
          description: Listings added during the window.
        sold_window:
          type: integer
          description: Sales closed during the window.
        source:
          type: string
          description: Which source supplied this record.
      description: Real-estate activity over the window.
    ChangePayload:
      type: object
      properties:
        permits:
          type: object
          properties:
            total:
              type: integer
              description: Total number of items in the window.
            total_value_usd:
              type: number
              description: Total estimated value of the permits, USD.
            by_type:
              type: object
              additionalProperties:
                type: integer
              description: Count of items of each type, keyed by type.
            recent:
              type: array
              items:
                $ref: '#/components/schemas/PermitEvent'
              description: The most recent items in the window.
          description: Building-permit activity in the window.
        business_changes:
          type: object
          properties:
            total:
              type: integer
              description: Total number of items in the window.
            by_type:
              type: object
              additionalProperties:
                type: integer
              description: Count of items of each type, keyed by type.
            recent:
              type: array
              items:
                $ref: '#/components/schemas/BusinessEvent'
              description: The most recent items in the window.
          description: Business openings, closings and changes in the window.
        real_estate:
          $ref: '#/components/schemas/RealEstateSnapshot'
        change_velocity:
          type: number
          minimum: 0
          maximum: 100
          description: How fast the block group is changing, 0–100.
      description: The change signal contents.
    ChangeSignal:
      type: object
      required:
        - fips
        - signal_layer
        - period_end
        - window_days
        - refreshed_at
        - payload
      properties:
        fips:
          type: string
          description: 12-digit US Census block group FIPS code.
        signal_layer:
          type: string
          enum:
            - change
          description: Which signal layer this record belongs to.
        period_end:
          type: string
          description: Last day of the period this record covers (`YYYY-MM-DD`).
        window_days:
          type: integer
          enum:
            - 30
            - 90
            - 180
            - 365
          description: Length of the rolling window, in days.
        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/ChangePayload'
      description: The current change 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.
        credits_remaining:
          type: integer
          description: Credits remaining on your account after 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
          properties:
            source:
              type: string
              description: The Motionworks dataset or model the result came from.
            data_maturity:
              type: string
              description: 'Maturity of the data behind the result: `production` (supported and stable), `research-preview` (available, subject to change), or a pre-release value (`roadmap`, or generated placeholder data not yet backed by production measurement).'
          description: Where the data came from and how mature it is.
      description: Request metadata.
    ChangeSignalResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ChangeSignal'
        meta:
          $ref: '#/components/schemas/Meta'
      description: One change signal with request metadata.
    ChangeHistorySnapshot:
      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.
        permit_count:
          type: integer
          description: Permits issued in the period.
        business_event_count:
          type: integer
          description: Business openings, closings and changes in the period.
        change_velocity:
          type: number
          description: Change-velocity score for the period, 0–100.
        data_quality:
          type: string
          description: 'Confidence in the signal: `high`, `medium` or `low`.'
      description: Change activity for one month.
    ChangeHistoryResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ChangeHistorySnapshot'
          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 monthly snapshots with request metadata.
    ChangeBatchRequest:
      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).
        window:
          type: integer
          enum:
            - 30
            - 90
            - 180
            - 365
          description: Rolling window in days (30, 90, 180 or 365).
      description: Block groups to look up and the window to use.
    ChangeBatchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ChangeSignal'
          description: The list of results.
        meta:
          $ref: '#/components/schemas/Meta'
      description: One change 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 Change
    tags:
      - change
x-customer-voice: true