Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The Custom Ads API contains two endpoints: one for which the location is defined in terms of the name of a geographic region, and the other for which it is defined in terms of latitude and longitude.

Info

Custom Ads by design contain no display information. If you wish to obtain pre-redendered ad units from CityGrid, see the Web Ads API for ads you can display on desktop browsers or the Mobile Ads API for ads you can display on mobile native and web applications.

...

Parameter

Description

Required

Valid Values

Default

Examples

Notes

what

What a user is searching for

Yes

 

 

pizza
sporting%20goods
plumbers

 

where

The geographic location, generally a zip code or city-state pair

See Notes below

A zip code, city-state pair, or street address (Spaces are optional following the comma between a city and state)

 

91011
Pasadena,%20CA 
Cambridge,MA 
1%20Main,Miami,FL

 

raw_what

The original user search phrase if available.

No

 

 

italian%20food
plumbing%20work

 

raw_where

The original user search phrase if available.

No

 

 

los%20angeles

 

radius

Radius of a circle search using client_ip.

No

An integer between 1 and 25, inclusive

25

2

If radius is larger than 25, it defaults to 25

publisher

The publisher code that identifies you

Yes

 

 

acme

This parameter is required so that we know who to credit

max

The Number of ads that you want to be returned

Yes

Integers, 1 through 10

10

3

Values over 10 will only return 10 results

placement

An optional property for storing additional information you would like CityGrid Media to log for this view

No

 

 

google
yahoo
searchresults

An example: if you are re-syndicating advertisements, you can use this parameter to record the ultimate destination for the advertisement. If you are placing CityGrid advertisements on your own site, you can record where on your site the advertisement will be placed

mapping_url

A callback URL

No

 

 

See #Mapping URL for more information.

client_ip

The IP address of your client

See Notes below

IPv4 or IPv6

 

17.148.221.102

This is used to determine a geography if the where parameter is not supplied

user_agent

The version of browser or device the ad is served on

No

 

The user agent value from the request header

Mozilla%2F5.0+%28BlackBerry%3B+U%3B+BlackBerry+9800%3B
+en-US%29+AppleWebKit%2F534.1%2B+%28KHTML%2C+like
+Gecko%29+Version%2F6.0.0.246+Mobile+Safari%2F534.1%2B

 

serve_url

The URL of the requested page

No

 

 

http%3A%2F%2Fnational.citysearch.com%2Fprofile%2F10843791
%2Fbremerton_wa%2Fgehring_brothers_guns.html

 

sem_networkProperty for storing the network for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric Google, Bing, Ezanga etc.  
sem_network_sourceProperty for storing network source for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric Search network, Run of network, google.com etc.  
sem_affiliate_idProperty for storing an affiliate id for you to optimize your marketing campaigns against, if you do marketingNoInteger Publisher id e.g. 3  
sem_sub_affiliate_idProperty for storing sub-affiliate_id for you to optimize your marketing campaigns against, if you do marketingNoInteger Sub-publisher id e.g. 21  
sem_campaign_idProperty for storing campaign id for you to optimize your marketing campaigns against, if you do marketingNoInteger 45723  
sem_adgroup_idProperty for storing adgroup id you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric Generic Auto Parts  
sem_creative_idProperty for storing creative id for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric75202492
Find Auto Repair Parts 
swf1  
sem_queryProperty for storing a query for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric pizza
, sporting goods
  
sem_matched_keywordProperty for storing a matched keyword for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric construction  
sem_device Property for storing the device for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric mobile device, desktop etc.  
Note

Arguments must be properly URL-encoded (spaces as %20 or +, ampersands as %26, and so on).

...

Parameter

Description

Required

Valid Values

Default

Examples

Notes

what

What a user is searching for

Yes

 

 

pizza 
sporting%20goods 
plumbers

 

lat

Latitude of the center of a circle for a geographic search

See Notes below

 

 

37.65056

 

lon

Longitude of the center of a circle for a geographic search.

See Notes below

 

 

-119.03639

 

radius

Radius of a circle search.

See Notes below

An integer between 1 and 50, inclusive

4

2

If radius is larger than 25, it defaults to 25

raw_what

The original user search phrase if available.

No

 

 

italian%20food
plumbing%20work

 

raw_where

The original user search phrase if available.

No

 

 

los%20angeles

 

publisher

The publisher code that identifies you

Yes

 

 

acme

This parameter is required so that we know who to credit

max

The Number of ads that you want to be returned

Yes

Integers, 1 through 10

10

3

Values over 10 will only return 10 results

placement

An optional property for storing additional information you would like CityGrid Media to log for this view

No

 

 

google
yahoo
searchresults

An example: if you are re-syndicating advertisements, you can use this parameter to record the ultimate destination for the advertisement. If you are placing CityGrid advertisements on your own site, you can record where on your site the advertisement will be placed

mapping_url

A callback URL

No

 

 

See #Mapping URL for more information.

client_ip

The IP address of your client

See Notes below

IPv4 or IPv6

 

17.148.221.102

This is used to determine a geography if the where parameter is not supplied

user_agent

The version of browser or device the ad is served on

No

 

The user agent value from the request header

Mozilla%2F5.0+%28BlackBerry%3B+U%3B+BlackBerry+9800%3B
+en-US%29+AppleWebKit%2F534.1%2B+%28KHTML%2C+like
+Gecko%29+Version%2F6.0.0.246+Mobile+Safari%2F534.1%2B

 

serve_url

The URL of the requested page

No

 

 

http%3A%2F%2Fnational.citysearch.com%2Fprofile%2F10843791
%2Fbremerton_wa%2Fgehring_brothers_guns.html

 

sem_networkProperty for storing the network for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric Google, Bing, Ezanga etc.  
sem_network_sourceProperty for storing network source for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric Search network, Run of network, google.com etc.  
sem_affiliate_idProperty for storing an affiliate id for you to optimize your marketing campaigns against, if you do marketingNoInteger Publisher id e.g. 3  
sem_sub_affiliate_idProperty for storing sub-affiliate_id for you to optimize your marketing campaigns against, if you do marketingNoInteger Sub-publisher id e.g. 21  
sem_campaign_idProperty for storing campaign id for you to optimize your marketing campaigns against, if you do marketingNoInteger 45723  
sem_adgroup_idProperty for storing adgroup id you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric Generic Auto Parts  
sem_creative_idProperty for storing creative id for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric75202492
Find Auto Repair Parts 
swf-1  
sem_queryProperty for storing a query for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric pizza
sporting goods
  
sem_matched_keywordProperty for storing a matched keyword for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric construction  
sem_device Property for storing the device for you to optimize your marketing campaigns against, if you do marketingNoAlphanumeric mobile device, desktop etc.  
Note

Arguments must be properly URL-encoded (spaces as %20 or +, ampersands as %26, and so on).

...