INRIX documentation logo

The Visits API is an asynchonous API that allows you to specify a date range of up to one year for a given set of location polygons. The API returns summarized information about the people who visited those locations.

Response Data

The report downloads will be in gzipped csv format. The response will have 3 links. If a user has passed in a report name, the report name will be used as a prefix on the files. The suffix of the files will be: visit_data.csv.gz, home_location_data.csv.gz, and cross_location_data.csv.gz. For example, if a report name is “cafe_comparison”, the visit report would be called cafe_comparison_visit_data.csv.gz.

Visits Example

The visits report calculates, for a given set of search locations, the total number of visits to each location grouped by the year, month, day of month, day of week, and hour of day.

searchLocation year month dayOfMonth hourOfDay dayOfWeek totalVisits
stone_way_cafe_freemont 2019 10 21 16 1 2
cloud_city_maple_leaf 2018 11 21 16 1 1

Home Location Example

The home location report matches visitors to their home neighborhood at the census block level. This makes it easy to characterize visitor travel distances and trade areas associated with each location, as well as to match visits to demographics data. For a given set of search locations, the report calculates the total number of visits and the number of unique visitors seen grouped by a home neighborhood census block.

searchLocation homeLocation totalVisits uniqueVisitors
TARGET_3100_W_117Th_St 390351235012003 5 2
Dollar_General_Norwalk_Rd 391034030012023 1 1

Cross Location Example

The cross location report is similar to the home locations report, except that it looks at the sharing of visitors between locations. Each row in the cross locations report table describes the number of visitors who live in a particular census block that visited both of two different locations, as well as the number of visits made by these individuals to each of the two locations.

In the example below, three individuals living in census block 390351235012003 were observed visiting both the cloud_city_maple_leaf and the starbucks_freemont_ave stores. These three people visited cloud_city_maple_leaf six times, and starbucks_freemont_ave 12 times over the course of the analysis time period.

This report is useful for describing the amount of competition between two locations, the rate of same-brand cannibalization, the success of cross promotions, and a great number of other things.

homeLocation searchLocation_1 searchLocation_2 totalVisits_1 totalVisits_2 uniqueVisitors
390351235012003 cloud_city_maple_leaf starbucks_freemont_ave 6 12 3

https://analytics-visits.inrix.com/v1/visits

POST Send a visit report request

Parameters

  = required
Name Located In Type Description
reportName Body String The given name of the report which will be used in file naming and email notifications. Supported standard characters for the report name: “0-9 a-z A-Z -_.” Spaces are not recommended and may be removed. A max name length of 50.
dateRanges Body String The date range to include in the report. Only one date range is currently supported, with a max range of 1 yr.
locations Body String an array of geojson defining polygons for analysis. A max of 1000 locations per request.
emailAddresses Body String an array of email addresses to notify on report completion

Requests

Example visit report request accepted
Body
{
   "reportName":"local_100_1month",
   "dateRanges":[
      {
         "startDate":"2019-10-01",
         "endDate":"2019-10-31"
      }
   ],
   "emailAddresses":[
      "myemail@company.com",
      "another@company.com"
   ],
   "locations":[
      {
         "locationType":"zone",
         "locationName":"Billy McHale's",
         "geometry":{
            "type":"Polygon",
            "coordinates":[
               [
                  [
                     -122.31661325090886,
                     47.31273052548383
                  ],
                  [
                     -122.31684257977963,
                     47.31288691865668
                  ],
                  [
                     -122.31677150124074,
                     47.312936928003786
                  ],
                  [
                     -122.31653680795193,
                     47.31277871645269
                  ],
                  [
                     -122.31661325090886,
                     47.31273052548383
                  ]
               ]
            ]
         }
      },
      {
         "locationType":"zone",
         "locationName":"cafe_one_the_ave",
         "geometry":{
            "type":"Polygon",
            "coordinates":[
               [
                  [
                     -122.313677,
                     47.658512
                  ],
                  [
                     -122.313328,
                     47.658504
                  ],
                  [
                     -122.313325,
                     47.658422
                  ],
                  [
                     -122.313345,
                     47.658401
                  ],
                  [
                     -122.313682,
                     47.658402
                  ],
                  [
                     -122.313677,
                     47.658512
                  ],
                  [
                     -122.313677,
                     47.658512
                  ]
               ]
            ]
         }
      }
   ]
}

Responses

200 Success
{
  "copyright":"Copyright INRIX Inc.",
  "versionNumber":"v1",
  "createdDate":"2020-01-09T21:35:03.840Z",
  "result":{
     "reportId":"478d909d-29ba-4c62-9149-60dfdb47bfb8",
     "state":"QUEUED",
     "submittedOn":"2020-01-09T21:35:03.192Z",
     "type":"VISITS_DOWNLOAD",
     "errorCode":0,
     "userId":"dc17e4fb-f655-4f90-b958-c2fd93443222"
  }
} 
400 Bad request
500 Internal Error

GET Get status of a report

Parameters

  = required
Name Located In Type Description
reportId Path String The visits report id you were given in the post response. Used to get the returned data

Responses

200 Success
{
   "copyright":"Copyright INRIX Inc.",
   "versionNumber":"v1",
   "createdDate":"2020-01-10T01:08:48.183Z",
   "result":{
      "reportId":"478d909d-29ba-4c62-9149-60dfdb47bfb8",
      "state":"COMPLETED",
      "submittedOn":"2020-01-09T21:35:03.192Z",
      "type":"VISITS_DOWNLOAD",
      "errorCode":0,
      "userId":"dc17e4fb-f655-4f90-b958-c2fd93443222",
      "downloadUrls":[
         "https://analytics-visits.s3.us-west-2.amazonaws.com/reports/year%3D2020/month%3D01/day%3D09/report_id%3D478d909d-29ba-4c62-9149-60dfdb47bfb8/cross_location_data/local_100_1month_cross_location_data.csv.gz?X-Amz-Security-Token=atoken%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200110T010848Z&X-Amz-SignedHeaders=host&X-Amz-Expires=604799&X-Amz-Credential=ASIA4RLRCN4HKRUAOXGN%2F20200110%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=4a16c3d52119ac5b2f439ec0e41f6d6981492d6a8b2391f77e1afd4a0d583c75",
         "https://analytics-visits.s3.us-west-2.amazonaws.com/reports/year%3D2020/month%3D01/day%3D09/report_id%3D478d909d-29ba-4c62-9149-60dfdb47bfb8/home_location_data/local_100_1month_home_location_data.csv.gz?X-Amz-Security-Token=atoken%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200110T010848Z&X-Amz-SignedHeaders=host&X-Amz-Expires=604799&X-Amz-Credential=ASIA4RLRCN4HKRUAOXGN%2F20200110%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=1837e87312af1936ff2c614f2ff294bc97328b66a7cbbec7f28bf164aecae2db",
         "https://analytics-visits.s3.us-west-2.amazonaws.com/reports/year%3D2020/month%3D01/day%3D09/report_id%3D478d909d-29ba-4c62-9149-60dfdb47bfb8/visit_data/local_100_1month_visit_data.csv.gz?X-Amz-Security-Token=atoken%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200110T010848Z&X-Amz-SignedHeaders=host&X-Amz-Expires=604799&X-Amz-Credential=ASIA4RLRCN4HKRUAOXGN%2F20200110%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=e23b9518f8cc1cfc59b919291a2298c6293c7e17204c3d0a9b00e6425aa4af4b"
      ]
   }
}
404 visit report id not found
500 Internal Error