CityGrid Advertising APIs
Call Detail Reporting API v2
Introduction
You are not looking at the most recent version of the Call Detail Reporting API, see here for the updated version
The CityGrid Call Detail Reporting API is part of the Advertising API suite and generates a list of phone calls tracked by the metered phone line for a particular place within an ad group. Report information is available in both JSON or CSV.
Contents
Call Detail Report Endpoint
The Call Detail Report endpoint returns a list of phone calls made through the metered phone line. The operation is invoked via HTTPS GET or POST to:
Request Parameters
Parameter | Description | Required | Type | Default | Example |
---|---|---|---|---|---|
| The AdGroup IDs for lookup, comma-separated. | Yes | Long | N/A | 123 |
| Date range for the report (case sensitive). Cannot be used with startDate and endDate. | No | yesterday | yesterday | last7Days |
| Start date (inclusive) for the report date range to query. | Yes if endDate is used. | Date (formatted as MM-DD-YYYY) | N/A | 11-17-2012 |
| End date (inclusive) for the report date range to query. | Yes if startDate is used. | Date (formatted as MM-DD-YYYY) | N/A | 11-17-2012 |
billing1
refers to the most recent billing cycle, billing2
to the billing cycle just before billing1
, and billing3
to the billing cycle just preceding billing2
.
Request Header Values
Header | Description | Required | Valid Values |
---|---|---|---|
| Media type of the request body, if any | Only if POST |
|
| Requested format for the response | Yes |
|
| Authentication Token from the Call Detail Reporting API v2 | Yes | Valid token |
| The token received during registration | Yes | Valid token |
Request Examples
Example 1: Request the call details from the last 14 days for the campaign listing designated by adGroupId 626642 (JSON format, HTTPS GET)
curl -X GET \ -H 'Accept:application/json' \ -H 'authToken:mytoken' \ 'https://api.citygrid.com/advertising/performance/v2/adgroup/calldetail?adGroupId=626642&period=last14Days'
Example 2: Request the call details from the last billing cycle for ad groups, 1, 7987, and 98003 (CSV format, HTTPS POST)
curl -X POST \ -H 'Accept:application/csv' \ -H 'Content-Type:application/json' \ -H 'authToken:mytoken' \ -d '{"adGroupId":"1,626642,617502", "period":"billing3"}' \ 'https://api.citygrid.com/advertising/performance/v2/adgroup/calldetail'
Example 3: Request the call details for 11-01-2012 (inclusive) to 11-15-2012 (inclusive).
curl -X GET \ -H 'Accept:application/json' \ -H 'authToken:mytoken' \ 'https://api.citygrid.com/advertising/performance/v2/adgroup/calldetail?adGroupId=626642&startDate=11-01-2012&endDate=11-15-2012'
Response Properties
Property | Type | Description |
---|---|---|
| Long | Ad Group ID |
| String | URL to access call recording if one is available |
| {Normal, Busy, Missed} | How the call was completed. |
| List | Top-level element for results |
| String | Unique ID for the call |
| String | The caller's phone number |
| String | The CityGrid metered line |
| Integer | The length of the call in seconds |
| String | The "ring to" phone number for the merchant |
| Response Metadata | |
| String | The start date and time of the call in ISO 8601 format with the offset given in hours (no minutes and seconds). Examples: |
| Integer | Total number of results |
Response Examples
JSON Success Response
{ "totalNumEntries": "3", "callDetails": [ { "adGroupId": "29674552", "callId": "8A40430580BB45408F3F3EA43F588EAC", "startTime": "2012-12-24T12:51:11-08", "duration": "34", "providerPhone": "3239541020", "displayPhone": "3236173630", "callerPhone": "3107488768", "audioUrl": "https:\/\/webservice.telmetrics.com\/filedownload.ashx\/68a-781d-4603-aeca-5434b7ab\/1505943738.mp3", "callCompletionCode": "Normal", "response": { "code": "SUCCESS", "message": "Success", "field": "" } }, { "adGroupId": "29674552", "callId": "A4267F8244584B4DAB3C9D7C973ED92F", "startTime": "2012-12-29T08:21:51-08", "duration": "49", "providerPhone": "3239541020", "displayPhone": "3236173630", "callerPhone": "8184428282", "audioUrl": "https:\/\/webservice.telmetrics.com\/filedownload.ashx\/fec-2dc7-4e2f-a011-ef7ef34bd5c8\/1506444753.mp3", "callCompletionCode": "Normal", "response": { "code": "SUCCESS", "message": "Success", "field": "" } }, { "adGroupId": "1", "callId": "", "startTime": "", "duration": "", "providerPhone": "", "callerPhone": "", "dislayPhone": "", "audioUrl": "", "callCompletionCode": "", "response": { "code": "DATA_NOT_FOUND", "message": "There is no data for This adGroupId.", "field": "" } } ], "response": { "code": "SUCCESS", "message": "Success", "field": "" } }
CSV Success Response
Error rendering macro 'code': Invalid value specified for parameter 'lang'adGroupId,callId,startTime,providerPhone,displayPhone,callerPhone,duration,audioUrl,code,message,callCompletionCode 29674552,8A40430580BB45408F3F3EA43F588EAC,2012-12-24T12:51:11-08,3239541020,3236173630,3107488768,34,https://webservice.telmetrics.com/filedownload.ashx/616a6a8a-781d-4603-aeca-51b72624b7ab/1505943738.mp3,SUCCESS,Success,Normal 29674552,A4267F8244584B4DAB3C9D7C973ED92F,2012-12-29T08:21:51-08,3239541020,3236173630,8184428282,49,https://webservice.telmetrics.com/filedownload.ashx/fe3f066c-2dc7-4e2f-a011-ef7eee3bd5c8/1506444753.mp3,SUCCESS,Success,Normal 9,,,,,,,,DATA_NOT_FOUND,There is no data for this adGroupId.,
JSON Error Response
A request for the following (note "Last14Dayz" instead of the required "last14Days")
{ "totalNumEntries": "", "callDetails": [ ], "response": { "code": "PARAMETER_INVALID", "message": "The parameter, period, was invalid. Valid options are billing1, billing2, billing3, last14Days, last30Days, last7Days, lastBusinessWeek, lastMonth, lastWeek, thisMonth, yesterday.", "field": "period" } }
CSV Error Response
A request for the following (note "Last14Dayz" instead of the required "last14Days")
api.citygrid.com/advertising/performance/v2/places/daily?placeId=1234&period=Last14Dayz code,message,field PARAMETER_INVALID,The parameter, period, was invalid. Valid options are billing1, billing2, billing3, last14Days, last30Days, last7Days, lastBusinessWeek, lastMonth, lastWeek, thisMonth, yesterday.,period