Number of Visitors Report - GET /api/report/{domain-id}/visitors

Reports ››
Parent Previous Next

GET /api/report/{domain-id}/visitors            

Get the number of daily visitors to a domain or domains.  Domain-id is a unique ID representing a domain. It is returned when you create a domain.  Request parameters allow you to specify a time period, timezone, and either a daily or hourly breakdown of visitors for the output.  The API will return the total number of visitors during the entire day even if the period is a portion of the day.


Request Details


Request Headers


Header

Description

Required

Authorization

Authorization string for the request

Yes

Host

URI for the QUANTIL SDK (i.e., api.quantil.com)

Yes

Date

The date and time of the request.

Yes

Accept

Indicates the accepted format (i.e., application/xml)

Yes

Request Parameters

Parameter

Description

Required

datefrom

RFC3339 formatted date indicating the starting date. Example: 2013-01-01T22:30:00+08:00

Yes

dateto

RFC3339 formatted date indicating the ending date. Example: 2013-01-01T22:30:00+08:00.  If the <datefrom> and <dateto> values are the same, we will return the breakdown of visitors by hour.

Yes

timezone

Indicates the timezone for the report data. It must be relative to GMT and specified in the format GMT+n where  -12<= n <= 12.  For example, timezone=GMT-7  and timezone=GMT+8.  If the parameter is unspecified, results will be in the GMT timezone.

No

type

Specify daily to get the total number of visitors grouped by day. Specify hourly to get the visitors grouped by each hour.

Yes


Request Body Elements

This request does not include an XML document in the request body.


Request Syntax:


GET /api/report/{domain-id}/visitors HTTP/1.1

Authorization: <authorization string>

Host: api.quantil.com

Date: <date>

Accept: application/xml


Here is the structure of a request using the curl utility.


curl -i --url https://api.quantil.com/api/report/ {domain-ID} /visitors ?datefrom = {date from} & dateto = {date to} & timezone = {timezone} &type={type}

-X GET

-u {user}: {password}

-H 'Date: Fri, 26 Oct 2012 06:33:26 GMT'

-H 'Accept: application/xml'

Sample Request:


curl -i --url 'https://api.quantil.com/api/report/214/visitors?datefrom=2014-08-01T00:00:00%2B09:00&dateto=2014-08-05T23:59:59%2B09:00&type=daily' -u test:Cayfj0uUFZthh+JCJQRS5UrwLSg= -H 'Date: Thu, 07 Aug 2014 17:41:10 PDT' -H 'Accept: application/xml'

Response Details:


Response Headers:

HTTP/1.1 200 OK

Date: <date>

Content-Type: application/xml; charset = utf-8

x-cnc-request-id: {id string auto generated by the QUANTIL server}



Response Body Elements


Element

Description

visitor-report

container for visitor information. It will contain zero or more <visitor-data> child elements describing the number of visitors who visited during a particular time.

visitor-data

indicates the number of visitors to a domain during a period of time. It contains one <timestamp> element and a <visitors> element.

hit-data

this container object contains a <timestamp> element and a <hit> element with the number of requests for content

timestamp

indicates the date. If <datefrom> and <dateto> are specified as different periods, then the timestamps will be the day in YYYY-MM-DD format (2014-07-31).  If the time period is the same, we return data for each hour of the day, so the timestamp will be in YYYY-MM-DD HH:mm:ss format (2014-07-31 01:00:00)

visitors

indicates number of visitors

Sample Response:


Example 1 shows data for daily visitors.



HTTP/1.1 200 OK

Date: Fri, 08 Aug 2014 20:12:06 GMT

Accept-Ranges: bytes

Server: Restlet-Framework/2.1.0

x-cnc-request-id: 27508

ContentType: application/xml;charset=UTF-8

Content-Type: application/xml;charset=UTF-8

Content-Length: 636


<visitor-report>

 <visitor-data>

   <timestamp>2014-07-31</timestamp>

   <visitors>7</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01</timestamp>

   <visitors>12</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-02</timestamp>

   <visitors>8</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-03</timestamp>

   <visitors>3</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-04</timestamp>

   <visitors>7</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-05</timestamp>

   <visitors>13</visitors>

 </visitor-data>

</visitor-report>


Example 2 shows visitors during each hour of a day:


HTTP/1.1 200 OK

Date: Fri, 08 Aug 2014 20:19:14 GMT

Accept-Ranges: bytes

Server: Restlet-Framework/2.1.0

x-cnc-request-id: 27512

ContentType: application/xml;charset=UTF-8

Content-Type: application/xml;charset=UTF-8

Content-Length: 2650


<visitor-report>

 <visitor-data>

   <timestamp>2014-08-01 01:00:00</timestamp>

   <visitors>2</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 02:00:00</timestamp>

   <visitors>2</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 03:00:00</timestamp>

   <visitors>1</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 04:00:00</timestamp>

   <visitors>1</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 05:00:00</timestamp>

   <visitors>1</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 06:00:00</timestamp>

   <visitors>1</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 07:00:00</timestamp>

   <visitors>1</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 08:00:00</timestamp>

   <visitors>2</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 09:00:00</timestamp>

   <visitors>2</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 10:00:00</timestamp>

   <visitors>1</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 11:00:00</timestamp>

   <visitors>1</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 12:00:00</timestamp>

   <visitors>1</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 13:00:00</timestamp>

   <visitors>1</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 14:00:00</timestamp>

   <visitors>0</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 15:00:00</timestamp>

   <visitors>1</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 16:00:00</timestamp>

   <visitors>0</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 17:00:00</timestamp>

   <visitors>1</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 18:00:00</timestamp>

   <visitors>3</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 19:00:00</timestamp>

   <visitors>0</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 20:00:00</timestamp>

   <visitors>0</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 21:00:00</timestamp>

   <visitors>0</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 22:00:00</timestamp>

   <visitors>0</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 23:00:00</timestamp>

   <visitors>0</visitors>

 </visitor-data>

 <visitor-data>

   <timestamp>2014-08-01 24:00:00</timestamp>

   <visitors>0</visitors>

 </visitor-data>


Error List


Error

Description

HTTP status code

InvalidDatePeriod

The date specified is invalid.

400

NoSuchDomain

The specified domain does not exist.

404