Placer Loyalty Reports API

openapi: 3.2.0
info:
  title: papi Account Info Loyalty Reports API
  description: Placer Public API
  version: 0.1-oas3
servers:
- url: https://papi.placer.ai
  x-amazon-apigateway-endpoint-configuration:
    disableExecuteApiEndpoint: true
security: null
tags:
- name: Loyalty Reports
paths:
  /v1/reports/loyalty/visits-frequency:
    post:
      summary: Visits by Frequency Report
      tags:
      - Loyalty Reports
      description: This service enables you to learn about the frequency of visitations to the requested POI.<br/> Insights are provided for all the below types of metrics, bucketed into visitations frequency bins (i.e. 1, 2, 3, …30+  visits per visitor):<br/> <ul> <li><strong>Visitors</strong> - The estimated number of unique visitors to the POI</li> <li><strong>% of Visitors</strong> - The % of unique visitors that visited the POI</li> <li><strong>Visits</strong> - The estimated number of visits to the POI</li> <li><strong>% of Visits</strong> - The % of visits generated by visitors to the POI </li> </ul> <br/><br/> &#128205; This service supports the <<glossary:Nearby Activity report>>. Once setting a value to the nearbyRadius parameter, the report will be generated based on the nearby activity logic.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VisitsFrequencyRequest'
      responses:
        '200':
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
            x-api-key:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisitsFrequencyResponse'
        '202':
          $ref: '#/components/responses/202_single'
        '400':
          $ref: '#/components/responses/400_bad_request'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      security:
      - api_key: []
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri: ${reports_lambda}
        passthroughBehavior: when_no_match
        timeoutInMillis: 29000
components:
  schemas:
    VisitDurationSegmentationRespReports:
      description: The default visit duration segmentation is returned when the report calculation uses the default segmentation duration.
      title: Visit Duration Segmentation
      type:
      - string
      - 'null'
      enum:
      - under10Min
      - 10MinOrLonger
      - allVisits
      - mixedSegments
      example: 10MinOrLonger
    BaseResponse:
      title: Base Response
      type: object
      required:
      - requestId
      properties:
        requestId:
          $ref: '#/components/schemas/RequestId'
    BaseVmFilterWithHours:
      allOf:
      - type: object
        properties:
          hoursRange:
            description: 'Filter the report’s results based on visits hours range. The filter is defined by 2 strings:<br/> 1. The starting hour to filter the reports results from (Format HH:MM XM, for example: 08:00 am).<br/> 2. The end hour to filter the reports results(Format HH:MM XM, for example: 11:59 pm) .'
            type: object
            required:
            - fromHour
            - toHour
            properties:
              fromHour:
                type: string
              toHour:
                type: string
            example:
              fromHour: 03:00 am
              toHour: 11:59 pm
      - $ref: '#/components/schemas/BaseVmFilterObject'
    VisitsFrequencyRequest:
      title: Visits Frequency Request
      allOf:
      - $ref: '#/components/schemas/DatesIdParams'
      - type: object
        properties:
          filter:
            $ref: '#/components/schemas/VmFilterObject'
          nearbyRadius:
            $ref: '#/components/schemas/NearbyRadius'
    ApiId:
      type: string
      example: venue:7d55054520e387813d764b03
      description: Placer API Entity Id
    StartDate:
      type: string
      format: date
      description: Queried data start date. Format YYYY-MM-DD
      example: '2020-12-01'
    BaseVmFilterObject:
      description: Filtering options for the report results.
      type: object
      properties:
        daysOfWeek:
          description: 'Filter visit calculation based on days of the week. Results will contain only requested days. Days are represented by using numbers where Monday=1 and Sunday=7. For example: in order to retrieve weekend days use the following [ 6, 7 ].'
          example:
          - 6
          - 7
          type: array
          items:
            enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
        distance:
          description: Filter visits by distance in miles from home <strong>or</strong> work<br/> where only visits in a given radius will be used in metrics calculation.
          example:
            from: home
            values:
              lt: 250
              gt: 10
          type: object
          properties:
            from:
              description: The origin from where the distance will be measured.
              type: string
              enum:
              - home
              - work
              example: home
            values:
              description: Object representation of the distance range<br/>lt - less than<br/>le - less than or equal to<br/>eq - equal to<br/>ge - greater than or equal to<br/>gt - greater than.
              example:
                gt: 10
                le: 100
              type: object
              properties:
                le:
                  type: number
                ge:
                  type: number
                lt:
                  type: number
                gt:
                  type: number
                eq:
                  type: number
    DatesIdParams:
      title: Base Report Request
      type: object
      required:
      - startDate
      - endDate
      - apiId
      properties:
        startDate:
          $ref: '#/components/schemas/StartDate'
        endDate:
          $ref: '#/components/schemas/EndDate'
        apiId:
          $ref: '#/components/schemas/ApiId'
    EndDate:
      type: string
      format: date
      description: Queried data end date. Format YYYY-MM-DD
      example: '2021-05-31'
    RequestId:
      type: string
      example: cfe57f50-fb64-11eb-8760-acde48001122:cfe56fce-fb64-11eb-8760-acde48001122
      description: Request ID that can be used for tracing
    VisitsFrequencyResponse:
      allOf:
      - $ref: '#/components/schemas/BaseResponse'
      - type: object
        properties:
          data:
            allOf:
            - $ref: '#/components/schemas/DatesIdParams'
            - type: object
              properties:
                avgVisitsPerCustomer:
                  type: number
                  format: float
                  description: The average number of visits for per visitor to the POI
                  example: 1.88
                medianVisitsPerCustomer:
                  type: integer
                  description: The median number of visits for per visitor to the POI
                  example: 1
                bins:
                  type: array
                  description: 'The array represents bins for the number of visits. Each bin represents visits with frequency value between current bin value and the next. E.g. Bin #2 has a value of 2 and bin #3 has a value of 3. So in bin #2 represent the visits that occurred exactly 2 times. But bin #10 has the value of 10, and bin #11 has the value of 15. So bin #10 will include all the visits that occurred 10 times or more, but less than 15 times. The last bin is unbounded.'
                  items:
                    type: integer
                  example:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                  - 6
                  - 7
                  - 8
                  - 9
                  - 10
                  - 15
                  - 20
                  - 30
                visitors:
                  type: array
                  description: The estimated number of unique visitors to the POI correlated with the bins array.
                  items:
                    type: integer
                  example:
                  - 195397
                  - 42348
                  - 20053
                  - 9578
                  - 6046
                  - 3337
                  - 2013
                  - 1394
                  - 1282
                  - 3195
                  - 1163
                  - 385
                  - 219
                visitorsPercentage:
                  type: array
                  description: The % of unique visitors that visited the POI correlated with the bins array.
                  items:
                    type: number
                    format: float
                  example:
                  - 68.22
                  - 14.79
                  - 7
                  - 3.34
                  - 2.11
                  - 1.17
                  - 0.7
                  - 0.49
                  - 0.45
                  - 1.12
                  - 0.41
                  - 0.13
                  - 0.08
                visits:
                  type: array
                  description: The estimated number of visits to the POI correlated with the bins array.
                  items:
                    type: integer
                  example:
                  - 195397
                  - 84696
                  - 60159
                  - 38311
                  - 30230
                  - 20025
                  - 14089
                  - 11151
                  - 11534
                  - 35719
                  - 19090
                  - 8790
                  - 10029
                visitsPercentage:
                  type: array
                  description: The % of visits that visited the POI correlated with the bins array.
                  items:
                    type: number
                    format: float
                  example:
                  - 36.24
                  - 15.71
                  - 11.16
                  - 7.1
                  - 5.61
                  - 3.71
                  - 2.61
                  - 2.07
                  - 2.14
                  - 6.62
                  - 3.54
                  - 1.63
                  - 1.86
                nearbyRadius:
                  $ref: '#/components/schemas/NearbyRadius'
      - $ref: '#/components/schemas/filtersAndVisitsDurationSegmentationResp'
    ResponseFilters:
      type: object
      properties:
        audienceType:
          description: The list of audiences that is specified in the request filter.
          example:
          - visitors
          type: array
          items:
            type: string
            enum:
            - visitors
            - employees
            - residents
        dwellTime:
          description: 'The dwell time filter specified in the request, in case it was utilized.<br/> For example: “< 100” or “>= 10”'
          type: object
          properties:
            operator:
              description: Represents the operator used for defining the dwell time range for filtering the report data
              type: string
              enum:
              - <
              - '>='
              example: <
            value:
              description: Represents the number of minutes referred to when defining the dwell time range for filtering the report data
              type: integer
              example: 150
        hoursRange:
          description: The hours range that is specified in the request filter.
          type: object
          properties:
            fromHour:
              description: 'Start visits hour (Format HH:MM XM, for example: 08:00 am)'
              type: string
            toHour:
              description: 'End visitation hour (Format HH:MM XM, for example: 08:00 am)'
              type: string
          example:
            fromHour: 03:00 am
            toHour: 11:59 pm
        daysOfWeek:
          description: A list of days represented by integers (Monday=1, Sunday=7) as specified in the request filter, which was used in the report calculation.
          example:
          - 6
          - 7
          type: array
          items:
            enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
        distance:
          description: The visits considered for the report calculation by distance in miles from home <strong>or</strong> work as specified in the request filter.
          example:
            from: home
            values:
              lt: 250
              gt: 10
          type: object
          properties:
            from:
              description: The origin from where the distance will be measured.
              type: string
              enum:
              - home
              - work
              example: home
            values:
              description: Object representation of the distance range<br/>lt - less than<br/>le - less than or equal to<br/>eq - equal to<br/>ge - greater than or equal to<br/>gt - greater than.
              example:
                gt: 10
                le: 100
              type: object
              properties:
                le:
                  type: number
                ge:
                  type: number
                lt:
                  type: number
                gt:
                  type: number
                eq:
                  type: number
    filtersAndVisitsDurationSegmentationResp:
      type: object
      properties:
        filters:
          $ref: '#/components/schemas/ResponseFilters'
        visitDurationSegmentation:
          $ref: '#/components/schemas/VisitDurationSegmentationRespReports'
    VmFilterObject:
      description: Filtering options for the report results.
      allOf:
      - type: object
        properties:
          audienceType:
            description: If provided - metrics will be calculated based only on the specified types of audience.
            example:
            - visitors
            type: array
            items:
              type: string
              enum:
              - visitors
              - employees
              - residents
          dwellTime:
            description: Metrics will be calculated considering the requested dwell time range.
            type: object
            properties:
              operator:
                description: Less than (<) to Greater Equal (>=)
                type: string
                enum:
                - <
                - '>='
                example: <
              value:
                description: The wanted dwell time
                type: integer
                example: 150
      - $ref: '#/components/schemas/BaseVmFilterWithHours'
    NearbyRadius:
      type: integer
      enum:
      - 100
      - 250
      - 500
      - 750
      - 1000
      description: 'The radius requested for nearby activity report generation.</br> <strong>Note</strong>: When a value is populated for this attribute - the report will be calculated as per the <<glossary:Nearby Activity report>> logic.'
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header