openapi: 3.1.0
info:
  title: AwardWallet Point & Mile Values API
  version: "1.1.0"
  description: |
    Public read-only API returning AwardWallet's point and mile values, along with booking sample sizes.
    The payload is flattened as a single `providers` array. Each provider includes a `category` attribute.
    **Attribution requirement** is included in the `notice` object and must be respected by clients.
  termsOfService: https://awardwallet.com/terms
  contact:
    name: AwardWallet Support
    url: https://awardwallet.com/contact
    email: support@awardwallet.com
  license:
    name: Use permitted with attribution to AwardWallet; link to source required.
    url: https://awardwallet.com/point-mile-values
servers:
  - url: https://loyalty.awardwallet.com/v1
    description: Production Loyalty API
paths:
  /point-mile-values/list:
    get:
      summary: Get point & mile values (flattened providers)
      description: |
        Returns current AwardWallet point and mile valuations as a flat list of providers.
        Each item contains a `category` field to identify the program type.

        **Attribution requirement**  
        You are free to use these values in your products **if and only if** you reference AwardWallet and
        the source page https://awardwallet.com/point-mile-values, and state:
        "Point and mile values are calculated and managed by AwardWallet."
      operationId: listPointMileValues
      parameters:
        - in: query
          name: unit
          description: Desired unit for values. Currently only `USD_cents_per_point` is supported.
          required: false
          schema:
            type: string
            enum: [USD_cents_per_point]
            default: USD_cents_per_point
        - in: query
          name: category
          description: Optional filter by provider category.
          required: false
          schema:
            $ref: '#/components/schemas/CategoryType'
        - in: query
          name: provider
          description: Optional provider filter (e.g., "Marriott Bonvoy", "United MileagePlus").
          required: false
          schema:
            type: string
        - in: query
          name: has_brands
          description: If true, returns only hotel providers that include brand breakdowns.
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: Valuations returned successfully.
          headers:
            ETag:
              description: Strong validator for caching the payload (matches `meta.data_hash`).
              schema:
                type: string
            Cache-Control:
              description: Suggested caching policy for clients and CDNs.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValuesResponse'
              examples:
                sample:
                  summary: Example flattened payload
                  value:
                    notice:
                      usage_guidelines:
                        - "You are free to use AwardWallet point and mile values in your products."
                        - "You must reference AwardWallet and the specific page https://awardwallet.com/point-mile-values."
                        - "You must state: \"Point and mile values are calculated and managed by AwardWallet.\""
                      source_name: "AwardWallet Point & Mile Values"
                      source_url: "https://awardwallet.com/point-mile-values"
                    meta:
                      version: "1.1"
                      generated_at: "2025-09-11T12:00:00Z"
                      unit: "USD_cents_per_point"
                      license: "Use permitted with attribution to AwardWallet; link to source required."
                      data_hash: "c9b6f0d2f3e14d0db3e7c2f0c1a9a8fb"
                      notes: "Numbers below are sample data for schema demonstration only."
                    providers:
                      - category: "Transferable Points"
                        provider: "American Express Membership Rewards"
                        average_value: 1.8
                        regional:
                          economy_premium: 1.4
                          business_first: 2.2
                        global:
                          economy_premium: 1.6
                          business_first: 2.6
                        bookings_sample_size: 4213
                      - category: "Airline Miles"
                        provider: "United MileagePlus"
                        average_value: 1.3
                        regional:
                          economy_premium: 1.1
                          business_first: 1.6
                        global:
                          economy_premium: 1.2
                          business_first: 1.8
                        bookings_sample_size: 4784
                      - category: "Hotel Points"
                        provider: "Marriott Bonvoy"
                        average_value: 0.8
                        bookings_sample_size: 6120
                        brands:
                          - brand: "Moxy"
                            average_value: 0.7
                            bookings_sample_size: 350
                          - brand: "Courtyard"
                            average_value: 0.7
                            bookings_sample_size: 900
                      - category: "Bank Rewards"
                        provider: "Wells Fargo Rewards"
                        average_value: 1.0
                        bookings_sample_size: 0
                        notes: "Cash-back pegged at 1 cent per point; sample size may be N/A."
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests.
          headers:
            Retry-After:
              description: Seconds until the client can retry.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Valuations
components:
  schemas:
    ValuesResponse:
      type: object
      required: [notice, meta, providers]
      properties:
        notice:
          $ref: '#/components/schemas/Notice'
        meta:
          $ref: '#/components/schemas/Meta'
        providers:
          type: array
          description: |
            Flat list of providers. The `category` field discriminates which schema applies.
          items:
            oneOf:
              - $ref: '#/components/schemas/TransferableProvider'
              - $ref: '#/components/schemas/AirlineProvider'
              - $ref: '#/components/schemas/HotelProvider'
              - $ref: '#/components/schemas/BankRewardsProvider'
            discriminator:
              propertyName: category
              mapping:
                Transferable Points: '#/components/schemas/TransferableProvider'
                Airline Miles: '#/components/schemas/AirlineProvider'
                Hotel Points: '#/components/schemas/HotelProvider'
                Bank Rewards: '#/components/schemas/BankRewardsProvider'
    Notice:
      type: object
      description: Rules of engagement and attribution requirements.
      required: [usage_guidelines, source_name, source_url]
      properties:
        usage_guidelines:
          type: array
          items:
            type: string
        source_name:
          type: string
        source_url:
          type: string
          format: uri
    Meta:
      type: object
      required: [version, generated_at, unit, license, data_hash]
      properties:
        version:
          type: string
          example: "1.1"
        generated_at:
          type: string
          format: date-time
        unit:
          type: string
          enum: [USD_cents_per_point]
        license:
          type: string
          description: Machine-readable license line for clients to display alongside attribution.
        data_hash:
          type: string
          description: Stable hash of the response payload for cache validation (matches ETag).
        notes:
          type: string
          nullable: true
    CategoryType:
      type: string
      enum:
        - Transferable Points
        - Airline Miles
        - Hotel Points
        - Bank Rewards
    CabinBreakdown:
      type: object
      description: Value by region and cabin grouping.
      required: [economy_premium, business_first]
      properties:
        economy_premium:
          type: number
          format: float
        business_first:
          type: number
          format: float
    BaseProvider:
      type: object
      required: [category, provider, average_value, bookings_sample_size]
      properties:
        category:
          $ref: '#/components/schemas/CategoryType'
        provider:
          type: string
        average_value:
          type: number
          description: Valuation in `USD_cents_per_point`.
          format: float
        bookings_sample_size:
          type: integer
          minimum: 0
    TransferableProvider:
      allOf:
        - $ref: '#/components/schemas/BaseProvider'
        - type: object
          properties:
            category:
              const: Transferable Points
            regional:
              $ref: '#/components/schemas/CabinBreakdown'
            global:
              $ref: '#/components/schemas/CabinBreakdown'
          required: [regional, global]
    AirlineProvider:
      allOf:
        - $ref: '#/components/schemas/BaseProvider'
        - type: object
          properties:
            category:
              const: Airline Miles
            regional:
              $ref: '#/components/schemas/CabinBreakdown'
            global:
              $ref: '#/components/schemas/CabinBreakdown'
          required: [regional, global]
    HotelProvider:
      allOf:
        - $ref: '#/components/schemas/BaseProvider'
        - type: object
          properties:
            category:
              const: Hotel Points
            brands:
              type: array
              description: Present for chains like Hilton, Hyatt, Marriott, IHG, Wyndham.
              items:
                $ref: '#/components/schemas/HotelBrand'
    HotelBrand:
      type: object
      required:
        - brand
        - average_value
        - bookings_sample_size
      properties:
        brand:
          type: string
        average_value:
          type: number
          format: float
        bookings_sample_size:
          type: integer
          minimum: 0
    BankRewardsProvider:
      allOf:
        - $ref: '#/components/schemas/BaseProvider'
        - type: object
          properties:
            category:
              const: Bank Rewards
            notes:
              type: string
              nullable: true
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          example: INVALID_ARGUMENT
        message:
          type: string
          example: One or more query parameters are invalid.
        details:
          type: object
          additionalProperties: true
tags:
  - name: Valuations
    description: Endpoints returning AwardWallet point and mile valuations.