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 Update

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

Sample Response (JSON)

{
"_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.