Sign in

v1

latestOpenAPI 3.0.12026-07-2433136135.1 KB
Visitor Journey Reports

Visitor Journey - Favorite Places

Favorite Places provides a list of other places that visitors to your location have also visited during the selected time frame (e.g., X% of visitors to My Venue also visited Place A during the last X months).<br/> You may choose specific categories to examine among the <a href="https://view-su2.highspot.com/viewer/87b4c810b4bc52f78f8fd2862fdf31dd">listed categories</a> and define the minimum visit frequency.<br/> The response includes the top 50 properties matching the requested parameters.<br/><br/> ⏱ <strong>Average measured processing time: 4.46 seconds </strong><br/> For more information on request retries best practices and processing measurements you may visit <a href="https://docs.placer.ai/reference/measurements"> this</a> page<br/><br/> 📍 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.

post/v1/reports/favorites-places

Request body

startDatestring date required

Queried data start date. Format YYYY-MM-DD

endDatestring date required

Queried data end date. Format YYYY-MM-DD

apiIdstring required

Placer API Entity Id

categoriesstring[]

Array of categories to which the resulted favorite places are associated. “all” will be used as default.<br/> NOTE: please select the specific categories from the <a href="https://view-su2.highspot.com/viewer/87b4c810b4bc52f78f8fd2862fdf31dd">listed categories</a>.<br/> If a list of categories is provided yet only some categories are recognized, results will reflect only the recognized categories. In case no category is recognized the results will reflect all categories.

minimalVisitFrequencyinteger

The minimal visits frequency requested in the other places/<glossary:chains>. 1 will be used as default.

limitinteger

The number of expected results. Default is set to 50.

nearbyRadius100 | 250 | 500 | 750 | 1000

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.

Example request

{
  "startDate": "2020-12-01",
  "endDate": "2021-05-31",
  "apiId": "venue:7d55054520e387813d764b03",
  "categories": [
    "gas stations & convenience stores",
    "airport facilities"
  ],
  "filters": {
    "audienceType": [
      "visitors"
    ],
    "dwellTime": {
      "operator": "<",
      "value": 150
    },
    "hoursRange": {
      "fromHour": "03:00 am",
      "toHour": "11:59 pm"
    },
    "daysOfWeek": [
      6,
      7
    ],
    "distance": {
      "from": "home",
      "values": {
        "lt": 250,
        "gt": 10
      }
    }
  }
}

Response

200 response

requestedCategoriesstring[]

The list of requested categories

nearbyRadius100 | 250 | 500 | 750 | 1000

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.

visitDurationSegmentation'under10Min' | '10MinOrLonger' | 'allVisits' | 'mixedSegments' nullable

The default visit duration segmentation is returned when the report calculation uses the default segmentation duration.

Example response

{
  "requestedCategories": [
    "gas stations & convenience stores",
    "airport facilities"
  ],
  "filters": {
    "audienceType": [
      "visitors"
    ],
    "dwellTime": {
      "operator": "<",
      "value": 150
    },
    "hoursRange": {
      "fromHour": "03:00 am",
      "toHour": "11:59 pm"
    },
    "daysOfWeek": [
      6,
      7
    ],
    "distance": {
      "from": "home",
      "values": {
        "lt": 250,
        "gt": 10
      }
    }
  },
  "visitDurationSegmentation": "10MinOrLonger",
  "favoritesPlacesArray": [
    {
      "apiId": "venue:7d55054520e387813d764b03",
      "name": "Walmart",
      "entityId": "7d55054520e387813d764b03",
      "entityType": "venue",
      "categoryInfo": {
        "category": "Fast Food & QSR",
        "group": "Dining",
        "subCategory": "Pizze Place"
      },
      "address": {
        "city": "Milpitas",
        "state": "California",
        "countryCode": "US",
        "streetName": "Ranch Dr",
        "formattedAddress": "301 Ranch Dr, Milpitas, CA, United States",
        "shortFormattedAddress": "Ranch Dr, Milpitas, CA",
        "zipCode": "95035"
      },
      "regions": {
        "dma": {
          "name": "San Francisco-Oakland-San Jose, CA"
        },
        "state": {
          "code": "CA",
          "name": "California"
        },
        "cbsa": {
          "code": "41940",
          "name": "San Jose-Sunnyvale-Santa Clara, CA Metro Area"
        }
      },
      "estimatedNumberOfCustomers": 1234,
      "percentage": 48.92,
      "distanceInMiles": 12.43
    }
  ]
}