API Documentation, version 1.0.

Contents

• Overview
• API Requests and Encoding
• Response Formats
• Retrieving Ads
• Obtaining an API Key
• Version

Overview

The Marchex Call Ad Network API allows publishers to query for pay-for-performance call-based ads in real time. Publishers can conduct a specific search for one or more ads, or request the full set of ads available to them for display.

Note: In order for phone calls to be properly tracked, the "ctn" field specified with each ad must be used. The "phone" field, if available, merely specifies the final number to which calls are directed after being tracked.

• Requests to the API are REST-like requests over HTTP.
• The REQUIRED parameter api_key is used to specify your API Key.
• The OPTIONAL parameter format can be used to specify a specific type of response.

Endpoints

API Requests and Encoding

The API expects all requests to be properly URL-encoded URIs.

For more information on URL encoding, please see Percent-encoding.

For more information on Uniform Resource Identifiers, please see RFC 3986.

A summary of allowed URI characters follows:

Response Formats

The Marchex Call Ad Network API supports responses in xml (default), json, and css.

All responses contain three sections:

• metadata - summary information for this transaction (response time, total ads, transaction id, etc.)
• ads - actual ad campaigns
• errors - error messages as appropriate for failed requests

Response Structure - Sample XML

	<?xml version="1.0" encoding="utf-8" ?>
	<response>
		<metadata>
			<elapsed_time>0.02</elapsed_time>
			<total_ads>2</total_ads>
			<transaction_id>87e1c6d86eec72f363b31258ac1f1ba7</transaction_id>
		</metadata>
		<ads>
			<ad>
				<id>123</id>
				<advertiser>allstate</advertiser>
				<title>Get insured today!</title>
				<ctn>18005551212</ctn>
				<address>123 Main Street</address>
				<city>Peoria</city>
				<state>IL</state>
			</ad>
			<ad>
				<id>456</id>
				<advertiser>geico</advertiser>
				<title>Insure your car today!</title>
				<ctn>18002343638</ctn>
				<address>200 Pine Street</address>
				<city>Seattle</city>
				<state>WA</state>
			</ad>
		</ads>
		<errors></errors>
	</response>

Response Structure - Sample JSON

	{
	"metadata":
		{
			"elapsed_time":0.02,
			"total_ads":2
		},
	"ads":[
		{
			"adid":123,
			"advertiser":"allstate",
			"title":"Get insured today!",
			"ctn":"18005551212",
			"address":"123 Main Street",
			"city":"Peoria",
			"state":"IL"
		},
		{
			"adid":456,
			"advertiser":"geico",
			"title":"Insure your car today!",
			"ctn":"18002343638",
			"address":"200 Pine Street",
			"city":"Seattle",
			"state":"WA"
		}
	],
	"errors":[]
	}

Retrieving Ads

Retrieve Full Set

Use this method to retrieve the full set of ads. Note that the response to this request may be rather large.

Sample request:

Search by Proximity

Use this method to select ads within a specific geographic region.

Sample request:

Search by Destination Phone

Use this method to select ads that direct paid calls to specific phone numbers.

Sample request:

Open Search

Use this method to search for ads based on specific criteria.

Sample request:

Obtaining an API Key

To obtain a valid publisher API key, please contact call-ad-network@marchex.com.

Version

This document represents version 1.0 of the Marchex Call Ad Network API.