Marchex Call Ad Network

API Documentation, version 1.0.


Contents


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.

Endpoints

http://call-ad-network-api.marchex.com/api/1_0/ads

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:

Summary of Valid URL Characters
SetCharactersURL usage
Alphanumeric a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 Text strings, scheme usage (http), port (8080), etc.
Unreserved - _ . ~ Text strings
Reserved ! * ' ( ) ; : @ & = + $ , / ? % # [ ] Control characters and/or Text Strings

Response Formats

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

All responses contain three sections:

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.

Method name: all
Calling styles: GET only
Parameters: none

Sample request:

http://call-ad-network-api.marchex.com/api/1_0/ads/all?api_key=f989b98d43b7f6ab42190261edbe5ef3

Search by Proximity

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

Method name: proximity
Calling styles: GET
Parameters:
  • latitude
  • longitude
  • radius
  • unit - mile or kilometer
  • Sample request:

    http://call-ad-network-api.marchex.com/api/1_0/ads/proximity?api_key=f989b98d43b7f6ab42190261edbe5ef3&latitude=47.610920&longtiude=-122.335437&radius=25&unit=mile

    Search by Destination Phone

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

    Method name: phones
    Calling styles: GET or POST (POST preferred)
    Parameters:
  • phones - comma separated list of NPANXXxxxx-formatted phone numbers
  • Notes:
  • Ads will contain a 'requested-phone' field that can be used to match the requested phone number to a matching ad
  • Sample request:

    http://call-ad-network-api.marchex.com/api/1_0/ads/phones?api_key=f989b98d43b7f6ab42190261edbe5ef3&phones=2125551212,8002343638

    Open Search

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

    Method name: search
    Calling styles: GET or POST
    Parameters:
  • city
  • state
  • zip
  • keywords
  • mode - and or or
  • Sample request:

    http://call-ad-network-api.marchex.com/api/1_0/ads/search?api_key=f989b98d43b7f6ab42190261edbe5ef3&zip=98101&keywords=legal&mode=and

    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.