Placer Loyalty Reports API

openapi: 3.2.0
info:
  title: papi 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.

        Insights are provided for all the below types of metrics, bucketed into visitations frequency bins (i.e. 1, 2, 3, …30+ visits per visitor):


        Visitors - The estimated number of unique visitors to the POI


        % of Visitors - The % of unique visitors that visited the POI


        Visits - The estimated number of visits to the POI


        % of Visits - The % of visits generated by visitors to the POI


        📍 This service supports the >. 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
      operationId: postV1ReportsLoyaltyVisitsFrequency
      x-operation-id-source: derived
components:
  schemas:
    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'
    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
    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'
    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'
    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'
    filtersAndVisitsDurationSegmentationResp:
      type: object
      properties:
        filters:
          $ref: '#/components/schemas/ResponseFilters'
        visitDurationSegmentation:
          $ref: '#/components/schemas/VisitDurationSegmentationRespReports'
    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.'
    RequestId:
      type: string
      example: cfe57f50-fb64-11eb-8760-acde48001122:cfe56fce-fb64-11eb-8760-acde48001122
      description: Request ID that can be used for tracing
    BaseResponse:
      title: Base Response
      type: object
      required:
      - requestId
      properties:
        requestId:
          $ref: '#/components/schemas/RequestId'
    ApiId:
      type: string
      example: venue:7d55054520e387813d764b03
      description: Placer API Entity Id
    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
    StartDate:
      type: string
      format: date
      description: Queried data start date. Format YYYY-MM-DD
      example: '2020-12-01'
    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
    EndDate:
      type: string
      format: date
      description: Queried data end date. Format YYYY-MM-DD
      example: '2021-05-31'
    VisitsFrequencyRequest:
      title: Visits Frequency Request
      allOf:
      - $ref: '#/components/schemas/DatesIdParams'
      - type: object
        properties:
          filter:
            $ref: '#/components/schemas/VmFilterObject'
          nearbyRadius:
            $ref: '#/components/schemas/NearbyRadius'
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header