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.
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:
Set | Characters | URL 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 |
The Marchex Call Ad Network API supports responses in xml (default), json, and css.
All responses contain three sections:
<?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>
{ "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":[] }
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:
Use this method to select ads within a specific geographic region.
Method name: | proximity |
Calling styles: | GET |
Parameters: |
|
Sample request:
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: |
|
Notes: |
|
Sample request:
Use this method to search for ads based on specific criteria.
Method name: | search |
Calling styles: | GET or POST |
Parameters: |
|
Sample request:
To obtain a valid publisher API key, please contact call-ad-network@marchex.com.
This document represents version 1.0 of the Marchex Call Ad Network API.