Introduction

The purpose of this API is to provide our partners with visibility of the traffic we're receiving from them (the number of connections per hour per listing). There are two endpoints of the api. The connections endpoint provides a summary of activity that may be considered billable by hour.  The data is meant to be accessed same-day before data has been processed and billable status as been finalized.  Therefore, some of the activity may be discounted at the end of the day.  A summary of calls received is available for previous days but not intra-day.

Authentication

Connections API has been updated (effective Jul 21, 2014):

1) The <PUBLISHER_CODE> parameter has been added to the HTTPS GET request path.

2) Authentication information will be the same as used for the Developer Center.


Publishers require a username and password to be able to access the Connections API. The credentials are the same as the credentials used for the Developer Center.

Connections

Engagement on the page as measured by clicks, such as "get directions", "view menu" et al. are accessed through the connection endpoint.  Data is delayed two hours (that is, you can view 8am data at 10am).

HTTPS Endpoint

 The following endpoint requires authentication and is used with HTTPS GET: 

https://api.citygrid.com/connection/<PUBLISHER_CODE>/<YYYY-MM-DD>

<PUBLISHER_CODE> should be modified to the actual Publisher Code.

 yyyy-mm-dd should be modified to the date of data desired as the four-digit year, 2-digit numerical month and 2-digit day of the month.

Response

The data is processed and updated intraday. The connection from last 30 days are available from the API. The table below describes the content of the response for connection endpoint.

Element

Parent Element

Attributes

Description

date

 

yyyy-mm-dd

Date for which data is requested.

The day is defined from 9 pm PST (previous day) to 9 pm PST (of the date specified). So for a given date, api will return data from 21 hours of the previous day.

Example – For date 2012-11-12, the data available will be from previous day’s 9 pm to 9 pm of 2012-11-12

publisher_code

 

 

Value of your publisher code

hour

publisher_code

The value ranges from 00 to 23

Hour of the day associated with the data

  • Passing 11 will give you data from 11 am to 12 pm.
  • The data available for the current day is up to 2 hours before the current hour. So, if it’s 2 pm now, the data available would be till 12 pm, so the api will have results for only 21 (from previous day) to 11 (of current day)

action target

hour

 

Event that was recorded. Example - “listing_driving_direction”

placement

action target

 

An optional property for storing additional information

listing id

placement

 

The ID to uniquely identify CityGrid's businesses

amount

listing id

 

Potential billable amount in USD

connections

listing id

 

Potential billable connections

{
"_id": "2013-10-26",
  "PUBLISHER_CODE": {
    "00": {
     "listing_driving_direction": {
        "PLACEMENT1": {
          "44876036": {
            "amount": 0.55,
            "connections": 1
          },
          "9840838": {
            "amount": 0.55,
            "connections": 1
          }
        }
      },
      "listing_map": {
        "listing_profile": {
          "10673245": {
            "amount": 0.55,
            "connections": 1
          },  
          "7489442": {
            "amount": 0.55,
            "connections": 1
          },
          "809724": {
            "amount": 0.55,
            "connections": 1
          },
          "9840838": {
            "amount": 1.1,
            "connections": 2
          }
        }
      }
    }
  }
}    

Calls

A summary of calls received is provided through the call endpoint.  Data is available at 6am EST.

HTTPS Endpoint

 The following endpoint requires authentication and is used with HTTPS GET: 

https://api.citygrid.com/connection/call/<PUBLISHER_CODE>/<YYYY-MM-DD>

<PUBLISHER_CODE> should be modified to the actual Publisher Code.

yyyy-mm-dd should be modified to the date of data desired as the four-digit year, 2-digit numerical month and 2-digit day of the month.

Response

Element

Attributes

Description

listing_id

 

The ID to uniquely identify CityGrid's businesses

campaign_product_id

 

The product associated with the provider to which the listing belongs. This is analogous to an AdGroup

ref_id

 

The ID to uniquely identify advertising partner to which listing belongs to

metered_phone

Yes/No

Whether or not a tracking line was in place. If no tracking line is available call data will be unavailable

 

total_calls

 

Total number of phone calls

billable_calls Number from total_calls which were considered billable. The definition of billable varies depending on the advertiser.

 

Sample response below

LISTING_ID

CAMPAIGN_PRODUCT_ID

REF_ID

METERED_PHONE

TOTAL_CALLS

BILLABLE_CALLS

2171421

19608692

15

No

0

0

3671731

7853122

1

No

0

0

4633768

48146

1

Yes

0

0

4663419

39018662

1

Yes

2

1

4751891

17345982

15

Yes

3

1

7484352

36483592

1

No

0

0

8911693

17028162

15

No

0

0

Disclaimer

The information provided from the API is meant to provide a quicker access to the partners as the traffic is delivered to CityGrid network. The finalized billable connections and amount will possibly vary from what's provided from the API.