Skip to end of metadata
Go to start of metadata

Introduction

The CityGrid Places API enables developers to create web and mobile applications that find local businesses, organizations, and points of interest by a variety of search criteria and display content associated with these places. Developers can use search results to position places on a map, perform further refinement or expansion searches, or access full details of a given place. Future versions of the Places API will allow submission of user reviews, photos, and other content.

Icon

If you qualify as a CityGrid partner, you can get paid for using the Places API through Places that Pay. Simply use the Places that Pay tracking features to notify CityGrid about impressions and referrals.

The Places API consists of two endpoint categories:

  • #Places Search — Returns the set of places that match your search criteria. Only basic place information is provided with each search result.
  • #Places Detail — Returns detailed information and associated content for a single place.

Contents

Audience

The Places API is intended for developers of web and mobile applications who want to give their applications the ability to search for and display profiles of local businesses and points of interest.

Version 2 Updates

 The following are changes for version 2, updated from version 1
  • Added support for SSL
  • New endpoint URLs beginning with http://api.citygridmedia.com/content/places/v2/.
  • New parameters for search requests:
    • histograms
    • lat2
    • lon2
    • has_offers
    • i (impression_id)
  • Changes to the Places Search response:
    • Added impression_id.
    • If there is no featured, an empty element is still provided in the response.
    • If there is no distance, an empty element is still provided in the response.
    • If there is no image, an empty element is still provided in the response.
    • If there is no fax_number, an empty element is still provided in the response.
    • If there is no tagline, an empty element is still provided in the response.
    • If there is no website, an empty element is still provided in the response.
    • If there is no has_video, an empty element is still provided in the response.
    • If there is no has_offers, an empty element is still provided in the response.
    • If there is no expansion, an empty element is still provided in the response.
    • If there are no spelling suggestions, an empty element/attribute is still provided in the response.
  • Changes involving geocoding:
    • For the XML response, there is now a regions element around a collection of region results.
    • If there are no regions, an empty element/attribute is still provided in the response.
  • Changes involving histograms, if histogramsis set to "true":
    • For the XML response, there is now a histograms element around a collection of histogram results.
    • For the XML response, there is now an items element around a collection of item results
    • If there are no histograms, an empty element/attribute is still provided in the response.
  • New parameters for detail requests:
    • i (impression_id)
    • image_count
    • image_size_min
    • image_size_max
  • Changes to the Places Details response:
    • Added impression_id.
    • review_dateeditorial_date, and offer_expiration_date are in ISO 8601 format.
    • For both JSON and XML responses, reviews has been renamed to review_info.
    • For the JSON response, review has been renamed to reviews.
    • For the XML response, there is now a reviews element around a collection of review elements.
    • Attributes nameid and parentid associated with category are now name_id and parent_id.
    • Attribute groupid associated with group is now group_id.
    • Attribute attributeid associated with attribute is now attribute_id.
    • For the JSON response, markets is now an array of strings.
    • For the JSON response, neighborhoods is now an array of strings.
    • For the JSON response, bullets is now an array of strings.
    • Added Google's Protocol Buffers as format option.
    • Added geographies.
  • Changes to Places details error codes:
    • Removal of review_count.out.of.range - If a supplied value is out of range, the default value is used (see Places Detail Request below).
    • Removal of format.unacceptable - If a supplied value is not one of the expected values (see Places Detail Request below), the response will be returned in XML.
    • Added image.count.illegal
    • Added image.count.out.of.range
    • Added image.size.range.invalid
    • Added image.size.illegal
  • Lat-Lon search with a radius of 0.25 miles or under no longer requires whattypetag or chain parameters

Places Search

The Places Search API provides programmatic access to CityGrid's local search engine, delivering basic place details together with metadata allowing subsequent refinement and expansion searches.

There are two endpoints for places search:

Search Using Where

The where endpoint returns places whose geography is specified with free-form text. The text can consist of a zip code, the name of a neighborhood or city, or a street address.

Where Search HTTPS Endpoint

The following endpoint supports HTTPS GET:

Where Search Request

The following query string parameters are used with the Places API where endpoint:

Parameter

Description

Required

Valid Values

Default

Examples

Notes

type

Restricts search to listings of the given type (category)

See Notes below.

movie
movietheater
restaurant
hotel
travel
barclub
spabeauty
shopping

 

movie
hotel
restaurant

A full list of types supported is available as a json list and as a json tree. Only one category may be provided.

what

Search term text

See Notes below.

 

 

pizza
sporting%20goods
plumbers

 

tag

Restricts search to listings with the given tag id

See Notes below.

An integer

 

1722

Tag ids are internal CityGrid identifiers and subject to change. A full list of types supported is available as a json list and as a json tree. This parameter may be used in queries that are obtained as "refinement urls" from previous searches

chain

Restricts search to listings with the given chain id.

See Notes below.

An integer

 

360861766
41859967

Chain ids are internal CityGrid identifiers and subject to change. This parameter should only be used in queries that are obtained as "chain expansion urls" from previous searches.

first

Restricts search to entities whose name begins with the given character, or if "#", then to entities beginning with any digit

No

A character

 

s
c

 

where

The geographic location

Yes

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

Address-based search is performed when this parameter starts with a number and contains non-numeric characters; it is much slower than searching a named region

page

The page number of the result set to display

No

Positive integer

1

8

 

rpp

Results per page

No

Positive integer between 1 and 50 inclusive

20

20

 

sort

Sort criterion for the results

No

dist
alpha
highestrated
mostreviewed
topmatches
offers

 

dist

Use alpha to sort results alphabetically, and dist to sort by increasing distance from the center of the search region. The dist request is only valid for address-based and circle searches.
If this parameter is omitted, the results will be ranked by relevance for keyword searches and distance for latitude and longitude

publisher

The publisher code that identifies you.

Yes

 

 

acme

 

format

The desired format for the results

No

json
xml
pbuf

xml

json

json = javascript object notation
xml = extensible markup language
pbuf = Google's Protocol Buffers

placement

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

No

 

 

 

An example: if you run a search engine marketing campaign for, say, Google and Yahoo!, you can set the placement property to "sem_google" or "sem_yahoo". Alternatively, if you publish CityGrid listings in different locations in your own site, you can set the placement property to values such as "home_page" or "search" (all up to you). CityGrid will organize reports for you by placement

has_offers

Restricts search to listings that have offers associated with them

No

true
false

false

true 
false

If this parameter is set to false it ignores the flag and returns all listings regardless of having offers.

histograms

Provide information on how many listings are in given groups and categories.

No

true
false

false

 

Turning on histograms can affect performance. More information is provided below.

call_idIddentify a single search requests over subsequent pages.    The value should be set when making subsequent calls for the same search, but a different page of the results. This user should never supply their own generated value for call_id, instead it should be taken from the search results's first page.
tag_refinementRestricts search to listings containing specific tags.NoTag(s) separated by comma. haircut,hair dyeThis is for getting results that match ALL tags. To search for results that match ANY tags use the what parameter
siteRestricts search to listings at a specific locationNoInteger 12345Site Ids are provided in Places Detail API response where valid. This is useful for finding all places at a given location (e.g. a mall, a shopping or medical center, etc.)


Note that there are four ways to specify the kind of places to return in a where search.

  • What. Use the what parameter and specify the geographic location
  • Type. Use the type parameter and specify the geographic location
  • Tag. Use the tag parameter and specify the geographic location
  • Chain. Use the chain parameter and specify the geographic location
    See #Specifying the Where Parameter for more details on how to specify the geographic location.

Where Search Usage Examples

The following table provides some example uses and their corresponding URL with query parameters. Click on the links to try them out.

Specifying the Where Parameter

To search for a location with a string, use the where endpoint and set the where parameter to the location's name or zip code. The CityGrid service will automatically parse the text and determine the geographical region to be searched.

Example: https://api.citygridmedia.com/content/places/v2/search/where?type=movietheater&where=90045&publisher=test

Depending on the value submitted, if successfully determined, one of six different types of areas may be searched. The table below describes the types of areas, as well as the default sort order in which the areas are returned.

Type

Examples

Default Order

Explanation

Cities

Los Angeles, CA
San Francisco, CA
Chicago, IL

Highest relevance first

 

Neighborhoods

Hollywood (Los Angeles, CA)
Midtown (Manhattan, NY)

Highest relevance first

 

Zip Codes

90210

Highest relevance first

 

Metro Areas

Los Angeles, CA Metro
New York, NY Metro

Highest relevance first

Expanded metropolitan regions, often including smaller neighboring cities

Addresses

1234 My Street, West Hollywood, CA

Smallest distance from the address first

A point-radius search is performed.

Intersections

Broadway and 7th Ave, Manhattan, NY

Smallest distance from the intersection first

A point-radius search is performed.

Note

Icon

If a single region cannot be determined by the value submitted, the response may contain a list of suggested regions (see #Geocoding.)

Search Using Latitude and Longitude

The latlon endpoint allows you to search for places using a geographic region defined by latitude and longitude.

LatLon Search HTTPS Endpoint

The following endpoint supports HTTPS GET:

LatLon Search Request

The following query string parameters are used with the Places API latlon endpoint:

Parameter

Description

Required

Valid Values

Default

Examples

Notes

type

Restricts search to listings of the given type

See Notes below.

movie
movietheater
restaurant
hotel
travel
barclub
spabeauty
shopping

 

movie 
hotel 
restaurant

A full list of types supported is available as a json list and as a json tree. Only one category may be provided.

what

Search term text

See Notes below.

 

 

pizza 
sporting%20goods 
plumbers

A full list of types supported is available as a json list and as a json tree

tag

Restricts search to listings with the given tag id

See Notes below.

An integer

 

1722

Tag ids are internal CityGrid identifiers and subject to change. A full list of types supported is available as a json list and as a json tree. This parameter may be used in queries that are obtained as "refinement urls" from previous searches.

chain

Restricts search to listings with the given chain id.

See Notes below.

An integer.

 

360861766 
41859967

Chain ids are internal CityGrid identifiers and subject to change. This parameter should only be used in queries that are obtained as "chain expansion urls" from previous searches.

first

Restricts search to entities whose name begins with the given character, or if "#", then to entities beginning with any digit

No

A character

 


c

 

lat

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

Yes.

 

 

37.65056

 

lon

Longitude of the center of a circle to search.

Yes

 

 

-119.03639

 

lat2

Second latitude used when performing a manual box search

See Notes below.

 

 

37.65056

lat2 and lon2 represents the lower right corner of the box

lon2

Second longitude used when performing a manual box search

See Notes below.

 

 

-119.03639

lat2 and lon2 represents the lower right corner of the box

radius

Radius of a circle search

See Notes below.

Positive number between 0 and 50 inclusive

5

7.5 

If larger than 50 it defaults to 50

page

The page number of the result set to display

No

Positive integer

1

8

 

rpp

Results per page

No

Positive integer between 1 and 50 inclusive

20

20

 

sort

Sort criterion for the results

No

dist
alpha
highestrated
mostreviewed
topmatches
offers

 

dist

Use alpha to sort results alphabetically, and dist to sort by increasing distance from the center of the search region. The dist request is only valid for address-based and circle searches. 
If this parameter is omitted, the results will be ranked by relevance for keyword searches and distance for latitude and longitude

publisher

The publisher code that identifies you.

Yes

 

 

acme

 

format

The desired format for the results

No

json
xml
pbuf

xml

json

json = javascript object notation
xml = extensible markup language
pbuf = Google's Protocol Buffers

placement

Store additional information you would like CityGrid Media to log for this view

No

 

 

 

An example: if you run a search engine marketing campaign for, say, Google and Yahoo!, you can set the placement property to "sem_google" or "sem_yahoo". Alternatively, if you publish CityGrid listings in different locations in your own site, you can set the placement property to values such as "home_page" or "search" (all up to you). CityGrid will organize reports for you by placement

has_offers

Restricts search to listings that have offers associated with them

No

true
false

false

true 
false

 

histograms

Provide information on how many listings are in given groups and categories.

No

true
false

false

 

Turning on histograms can affect performance. More information is provided below.

call_idIdentify a single search requests over subsequent pages.    The value should be set when making subsequent calls for the same search, but a different page of the results. This user should never supply their own generated value for call_id, instead it should be taken from the search results's first page.
tag_refinementRestricts search to listings containing specific tags.NoTag(s) separated by comma. haircut,hair dyeThis is for getting results that match ALL tags. To search for results that match ANY tags use the what parameter
siteRestricts search to listings at a specific locationNoInteger 12345Site Ids are provided in Places Detail API response where valid. This is useful for finding all places at a given location (e.g. a mall, a shopping or medical center, etc.)
Icon

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


Note that there are four ways to specify the kind of places to return in a lat-lon search.

  • Free-form Query. Use the what parameter and specify the geographic shape
  • Type. Use the type parameter and specify the geographic shape
  • Tag. Use the tag parameter and specify the geographic shape
  • Chain. Use the chain parameter and specify the geographic shape
  • All Places in a small radius. You can search without specifying the what, type, tag, or chain parameters by specifying a Point-Radius Circle search where the circle radius is 0.25 miles or less; in this case, all places within that radius will be returned.
    See #Specifying the Geography for more details on how to specify the geographic shape.

LatLon Search Usage Examples

The following table provides some example uses and their corresponding URL with query parameters. Click on the links to try them out.

Specifying the Geography

If you want to specify a geography to search for places in terms of latitude and longitude, there are two ways accomplish this:

Icon

These methods are mutually exclusive. Specifying parameters that belong to more than one method may result in either a geography.overspecified error or incorrect results.

Point-Radius

The point-radius search returns listings in a region with the specified radius. To use this search, specify the lat, lon, and radius parameters.

Example: https://api.citygridmedia.com/content/places/v2/search/latlon?type=movietheater&lat=34.03&lon=-118.28&radius=5&publisher=test

Usage

Icon

The point-radius search is good for when you desire listings that are near a location. Use for fast searches sorted by relevance.

Note that the point-radius search results can be computed either through a bounding circle or a bounding box; we reserve the right to change the implementation over time.

Box

The box search is similar to the point-radius search, except that it returns listings in a rectangular region rather than a square or circular one. It does not calculate distances between a place and a reference coordinate, so searches are often faster. To use this search, specify the lat, lon, lat2, and lon2 parameters.

Example: https://api.citygridmedia.com/content/places/v2/search/latlon?type=movietheater&lat=34.03&lon=-118.28&lat2=34.08&lon2=-118.23&publisher=test

Usage

Icon

The box search is good for when the two corner points can be determined easily, such as when a user can custom-define the region to be searched. An example of this is a click-and-drag map that can be panned and zoomed by a user, dynamically changing the search region.

When you specify the lat, lon, lat2, and lon2 parameters, the CityGrid service searches a rectangle where (lat,lon) and (lat2,lon2) represent points on two opposite corners of the rectangle. Results are returned sorted by relevance, most relevant results first. The distance from the center point is not returned.

Search Response

The Places Search results are returned in either XMLJSON, or Google's Protocol Buffers.

The following table describes the return elements:

Element

Parent Element

Attributes

Description

results

 

rpp - Number of results requested per page
page - Current page of results
last_hit - Position of the last result in this page of results out of the total number of hits
first_hit - Position of first result in this page of results out of the total number of hits
total_hits - Total number of hits that matched the search
query_id - Generated id associated with the search

Metadata regarding the search results.

uri

results

 

Request URL processed.

call_idresults Please send this as a parameter to search api when accessing the subsequent page of results for the same search request.
did_you_mean

results

 

Spelling suggestions if what parameter was provided and not enough results were retrieved.

regions

results

 

Because the geographic region provided in the where parameter contains free-form text, its value may be ambiguous. This is a collection of interpretations.

region

regions

type - The type of geography this region represents (e.g. city, neighborhood)

Because the geographic region provided in the where parameter contains free-form text, its value may be ambiguous. This is a collection of interpretations.

name

region

 

Name of the region.

latitude

region

 

Latitude associated with the region.

longitude

region

 

Longitude associated with the region.

default_radius

region

 

Approximate radius for the region.  Represents the value used for the radius if an address or intersection is used as a value for the where parameter.

locations

results

 

Collection of businesses that matched the search.

location

locations

id - The unique CityGrid Media identifier for this business listing

Representation of a single business or organization.

featured

location

 

True if a CityGrid customer, false if not.

public_id

location

 

The CityGrid id of the business listing.

name

location

 

The name of the business or organization.

address

location

 

The address of the business.

street

address

 

The street portion of the address.

city

address

 

The city portion of the address.

state

address

 

The state portion of the address.

postal_code

address

 

The postal code portion of the address.

neighborhood

location

 

The neighborhoods to which this business is associated.

latitude

location

 

The latitude of the listing.

longitude

location

 

The longitude of the listing.

distance

location

 

The distance from the supplied lat and lon during a point/radius search.

image

location

 

URL to an image associated with the business.

phone_number

location

 

The phone number of the business.

fax_number

location

 

The fax number of the business.

rating

location

 

The average user rating of the business.

tagline

location

 

The business' tagline.

profile

location

 

URL to the business' profile.

website

location

 

URL of business' website.

has_video

location

 

True if video content is available, false if not.

has_offers

location

 

True if offers are available, false if not.

offers

location

 

Text of the offer expiring the soonest.

user_reviews_count

location

 

Total number of user reviews of the business.

sample_categories

location

 

An abbreviated list of tags associated with the business.

impression_id

location

 

The internal impression id generated for tracking.

expansion

location

 

Currently not used.  Intended for businesses that are associated with chains/franchises.  

business_operation_status

location

 

The status of the business: open (a value of "1"), closed (a value of "0"), or unknown (a null value)

tags

location

 

Collection of all tags associated with this event

tag

tags

id - internal id associated with the tag

The name of a tag.

XML Response

The following is an example of an XML response with blank data.

JSON Response

The following is an example of a JSON response:

Notes

If a callback parameter is supplied, the JSON response will be wrapped in a call as follows:

Protocol Buffers Response

Google's Protocol Buffers is a format that can easily be processed by applications written in Java, C++, or Python. To use the protocol buffer format, run the protocol buffer compiler for your language on this proto file. The generated classes can then be used to populate, serialize, and read protocol buffer messages.

See Google's Tutorials for information on how to compile .proto files and use the generated classes.

Spelling suggestions

A query may return spelling suggestions if it appears that the user might have misspelled a word or listing. Spelling suggestions will appear in a didyoumean element. For example, a query containing what=computr+parts yields might return:

Geocoding

Because the geographic region given in the where parameter contains free-form text, its value may be ambiguous. If there is ambiguity, we provide a collection of possible interpretations, and perform a search on the first one listed. 

For example, the query string

might produce a result as follows:

In the example above, the geography term "Vail" matched five different regions. The webservice found "Vail, CO" to be the best match and placed it first. The geocode match that appears first is the one used to produce the results that follow. Clients are free to check for multiple geocoded regions and suppress displaying results to their own users if they wish. The geocoder may return a latitude, longitude and “default radius” for each region. The latitude and longitude represent an approximate center point for the corresponding region. The "default radius" is an approximate radius for the corresponding region, and represents the value used for the radius if an address or intersection is used as a value for the where parameter. See #Specifying the Geography for more details.

Icon

If a search returns zero results for the specified geography, the webservice will expand the search to a larger geographical location and search again. If no results are found in the expanded geography, the service will then return an empty result set.

Histograms

Histograms provide information on how many listings are in given groups and categories.

Histograms Optional

Icon

The histograms feature will be disabled by default. If you require histograms as part of the response, then include the query parameter histograms=true in the query. Generating histograms requires additional processing and may slow down the query, so if they're not needed, leave this turned off.

Each non-empty successful response contains a set of zero or more histograms that give the number of results for each tag. Each histogram also contains uris to carry out refinement searches. For example, a search for “food” in a 0.7 mile radius around zip code 90004 yields three histograms:

Icon

The refinement uri contains a tag parameter. The value of this parameter is valid for only a short period of time and should not be relied on for anything but a subsequent search.

Search Error Reporting

CityGrid Media provides error codes, rather than error messages. This allows you to customize the text and language for display. If a request can not be completed for any reason, an error document will be returned with a set of mnemonic error codes to help you troubleshoot the error.

Error Codes

A complete list of error codes follows:

Code

Description

query.underspecified

Neither type, what, tag, nor chain was specified

query.type.unknown

The query type parameter is not supported

query.overspecified

The parameter type was specified in addition to tag or chain

geography.underspecified

Neither where, lat, nor lon were given

geography.overspecified

Both where and one of lat or lon were given

radius.required

Both lat and lon were given, but radius was missing

geocode.failure

The geocoder could not find a match for the given where parameter

tag.illegal

The parameter tag was not an integer

chain.illegal

The parameter chain was not an integer

first.illegal

The parameter first was not a character

latitude.illegal

The parameter lat was not a valid number

longitude.illegal

The parameter lon was not a valid number

radius.illegal

The parameter radius was not a valid number

page.illegal

The parameter page was not an integer

rpp.illegal

The parameter rpp was not an integer

sort.illegal

The parameter sort contained an unknown value

radius.out.of.range

The parameter radius was below 1

page.out.of.range

The parameter page was less than 1

rpp.out.of.range

The parameter rpp was not in the range 1..50

publisher.required

The publisher parameter is missing

internal.error

An internal problem with the service occurred

XML Error Response

In the XML response, the error codes are contained within errors and error tags. 

Element

Parent Element

Description

errors

 

Root node. A Collection of errors.

error

errors

An error code. See the table of error codes above.

For example, the following request:

returns the following response:

JSON Error Response

In the JSON response, the error codes are values paired with error keys, as part of an errors array.

For example, the following request:

returns the following response:

Places Detail

The Places Details API provides programmatic access to CityGrid's local listings data, including businesses and events.

Detail HTTPS Endpoint

Detail Request

The following query string parameters are used with the Places API search endpoint:

Parameter

Description

Required

Valid Values

Default

Examples

Notes

id

An id used to identify a place

Yes, if listing_id, infousa_id, public_id, or phone is not provided. If used, then id_type must also appear.

An applicable id string

 

3151050

 

id_type

A corresponding type passed in with id

Yes, if using id

List of id types

 

cg

If you are switching from the deprecated parameters to the new parameters id and id_type, here is the corresponding id type mappings:
public_id : cg
listing_id : cs
infousa_id : iusa
For the full list of legal id_type values, look here

(DEPRECATED) listing_id

A unique numeric id identifying a customer's business.

Yes, if infousa_id, public_id, or phone is not provided.

Positive integer

 

3151050

This field is deprecated. It is still supported but will be removed from future version.

(DEPRECATED) public_id

A unique text id identifying a customer's business, useful in forming URLs.

Yes, if infousa_id, listing_id, or phone is not provided.

String

 

pinks-hot-dogs-los-angeles

This field is deprecated. It is still supported but will be removed from future version.

(DEPRECATED) infousa_id

The InfoUSA identifier of the business.

Yes, if listing_id, public_id or phone is not provided.

Positive integer

 

934233230

This field is deprecated. It is still supported but will be removed from future version.

phone

Requests listings with this phone number.

Yes, if listing_id, public_id or infousa_id is not provided.

10 digits with no spaces or dashes

 

3105551212

Up to a maximum of 25 will be returned.

publisher

The publisher code that identifies you.

Yes

 

 

acme

 

customer_only

Whether you wish to restrict the results to places of CityGrid customers only.

No

true
false

false

true

 

all_results

Whether you wish to have all results or as opposed to one result for a particular infousa_id or a phone.

No

true
false

false

true

 

review_count

The maximum number of reviews you want shown in the response.

No

Positive integer between 0 and 20 inclusive

3

10

 

exclude_editorial

Whether you wish to receive a review of type "editorial_review" in the response

No

true, false

false

true

 

offer_count

The maximum number of offers you want shown in the response

No

Positive integer between 0 and 10 inclusive

10

3

 

placement

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

No

 

 

sem_google
sem_yahoo
home_page
search

An example: if you run a search engine marketing campaign for Google and Yahoo!, you can set the placement property to "sem_google" or "sem_yahoo". Alternatively, if you publish CityGrid listings in different locations in your own site, you can set the placement property to values such as "home_page" or "search" (all up to you). CityGrid will organize reports for you by placement.

client_ip

The IP address of the client to whom you will be sending the place data.

Yes

Four numbers between 0 and 255 separated by periods.

 

123.45.67.89

 

format

The desired format for the results.

No

json
xml
pbuf

xml

json

  • json = javascript object notation
  • xml = extensible markup language
  • pbuf = Google's Protocol Buffers

callback

The name of (your own) JavaScript function that you would like to wrap your JSON response.

No

 

 

display
cache

 

i

An optional property for grouping API calls for tracking purposes. The parameter name is shortened from impression_id.

No

 

 

 

The value should be set when making subsequent calls that are related to a previously made call. The user should never supply their own generated value for the impression_id. For example, the impression_id from a Places Search API response would be used as a request to Places Detail API if the listing is clicked on.

mobile_type

 

This field designates publisher device type name or designates the usage of our content on your Wireless Application Protocol (WAP) site.

 

Required for mobile publishers

 

 

 

 

muid

The hash of user phone number and/or device ID as provided by the carrier. Max of 32 chars

Required for mobile publishers

 

 

 

 

ua

 

The client side user agent. Must be properly html encoded. Ignore if it's not.

 

Required for mobile publishers

 

 

 

 

sourcephone

The source phone for the click to call implementation on mobile phones. Could be the last 4,no dashes

Required for mobile publishers

 

 

 

 

image_count

An optional value that allows the user to limit the number of images returned.

No

0 and all positive 32-bit integers

 

0, 1, 50

 

image_size_min

An optional value that allows the user to return images that are of a minimum specified size.

No

A String consisting of the Width followed by the Height

 

100x200
50x150
1200x1200

When used in conjunction with the image_size_max parameter the width and height of the image_size_min parameter must be less than or equal to the image_size_max value.

image_size_max

An optional value that allows the user to return images that are of a maximum specified size.

No

A String consisting of the Width followed by the Height

 

100x200
50x150
1200x1200

When used in conjunction with the image_size_min parameter the width and height of the image_size_max parameter must be greater than or equal to the image_size_min value.

Icon

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

Icon

customer_message_url, listing_id, public_id, and infousa_id are deprecated. They will continue to work in this version but will eventually be removed in a future version. Please switch to using id and id_type as soon as possible.

Detail Usage Examples

The following table provides some example uses and their corresponding URL with query parameters. Click on the links to try them out.

Usage

URL

Find the place with listing id 10100230, placement "search_page", and client ip 123.4.56.78

https://api.citygridmedia.com/content/places/v2/detail?id=10100230&id_type=cs&placement=search_page&client_ip=123.4.56.78&publisher=test

Find the place with infousa ID of 412275828 and client IP of 123.124.123.124

https://api.citygridmedia.com/content/places/v2/detail?id=412275828&id_type=iusa&client_ip=123.124.123.124&publisher=test

Find the place with phone 323-256-9617 and client IP of 123.124.123.124

https://api.citygridmedia.com/content/places/v2/detail?phone=3232569617&client_ip=123.124.123.124&publisher=test

Find the place with phone 323-256-9617 and client IP of 123.124.123.124, and placement "search_page" and display all listings associated with that phone

https://api.citygridmedia.com/content/places/v2/detail?phone=3232569617&client_ip=123.124.123.124&placement=search_page&all_results=true&publisher=test

Find the place with phone 323-256-9617 and client IP of 123.124.123.124, and placement "search_page" and (at most) the first 10 reviews

https://api.citygridmedia.com/content/places/v2/detail?phone=3232569617&client_ip=123.124.123.124&placement=search_page&review_count=10&publisher=test

Detail Response

The Places Detail results are returned in either XML, JSON, or Google's Protocol Buffers.

The following table describes the return elements:

Element

Parent Element

Attributes

Description

locations

 

 

Wraps the returned places

location

locations

 

Representation of a single business or organization

id

location

 

The unique numeric identifier for the place, this is the CURRENT id for this place, if a merged or older id was used to search for this place, only the current id will be returned

public_id

location

 

The unique textual, url-friendly identifier for this place

infousa_id

location

 

The InfoUSA identifier for this place

reference_id

location

 

A secondary identifier for the place, used for tracking

impression_id

location

 

The internal impression id generated for tracking.

name

location

 

The name of the place

display_ad

location

 

Whether or not the ads should be displayed for this place

claimed

location

 

True if an owner has claimed their business and been verified by CityGrid

teaser

location

 

A brief, catchy line for the place

business_operation_status

location

 

The status of the business: open, closed, or unknown

address

location

 

Wraps the address individual address fields

years_in_business

location

 

Quantity in years that the place has been in business

last_update_time

location

 

Date that the place was last updated

street

address

 

The street portion of the address

delivery_point

address

 

An extension to the address (suite, floor, etc)

city

address

 

The city portion of the address

state

address

 

The state portion of the address

postal_code

address

 

The postal code portion of the address

cross_street

address

 

Cross street information

latitude

address

 

The latitude of the place

longitude

address

 

The longitude of the place

contact_info

location

 

Wraps the contact information fields

display_phone

contact_info

 

The phone number of the place to display

display_url

contact_info

 

The URL of the place to display

social_media

contact_info

 

Wraps contact info on supported social media platforms

twitter_username

social_media

 

Wraps twitter contact information

text

twitter_username

 

The Twitter handle

facebook_fanpage

social_media

 

Wraps facebook contact information

text

facebook_fanpage

 

The facebook username

url

facebook_fanpage

 

The URL of the place on facebook

markets

location

 

Wraps the returned markets

market

markets

 

Name of a single market

neighborhoods

location

 

Wraps the returned neighborhoods

neighborhood

neighborhoods

 

Name of a single neighborhood

urls

location

 

Wraps the set of urls for this place

profile_url

urls

 

The URL of the place on CityGrid

reviews_url

urls

 

The URL for the place's reviews

video_url

urls

 

The URL for the place's video

website_url

urls

 

The URL for the place's main website

menu_url

urls

 

The URL for the place's menu

reservation_url

urls

 

The URL at which one can make reservations for this place

map_url

urls

 

The URL for the listing's map

send_to_friend_url

urls

 

The URL at which one can notify friends about this place

email_link

urls

 

The URL at which one can email the place.

custom_link_1

urls

 

Additional URL provided by the place.

custom_link_2

urls

 

Additional URL provided by the place.

custom_link_3

urls

type - Type of link (i.e "menu")

Additional URL provided by the business.

custom_link_4

urls

type - Type of link (i.e "menu")

Additional URL provided by the business.

custom_linksurls List of custom urls provided by a merchant - these are the clicks they are most interested in.
typecustom_link The action_target the link corresponds to. A full list is available under Places That Pay
urlcustom_link The destination url of the link. This is usually to a specific page within an advertiser's website for lead gen (a form fill) or conversion (e.g. a booking). This is an obfuscated url and is not intended for a user to read.
display_textcustom_link The text to display for the URL. For example "View Brochure" or "Book Now!"
 

location

 

An encrypted Places that Pay tracking URL.

customer_content

location

 

Wraps the customer message, the customer message url, and the bullets

customer_message

customer_content

attribution_source - Unique identifier of the content provider
attribution_logo - The logo of the content provider (typically an 88 x 33 jpeg)
attribution_text - Name of the content provider, to be displayed in place of, or along side of, the attribution logo
attribution_url - The URL for the for content provider, to be linked to from the logo and text

A short message about this business written by or on behalf of its owner

customer_message_url (DEPRECATED)

customer_content

 

The URL hosting the customer message on Citysearch.com

bullets

customer_content

 

Wraps the bullet points of the customer message

bullet

bullets

 

An individual bullet point within the customer message

offers

location

attribution_source - Unique identifier of the content provider
attribution_logo - The logo of the content provider (typically an 88 x 33 jpeg)
attribution_text - Name of the content provider, to be displayed in place of, or along side of, the attribution logo
attribution_url - The url of the content provider

Wraps offer details

offer

offers

 

An offer

offer_name

offer

 

The name of the offer

offer_text

offer

 

The text of the offer

offer_description

offer

 

The description of the offer

offer_url

offer

 

The URL of the offer

offer_expiration_date

offer

 

The date on which the offer expires in ISO 8601 format.

categories

location

 

Wraps categorization information about this listing

category

categories

name_id - The CityGrid internal id of the category
name - The name of the category
parent_id - The id of the parent of the category
parent - The name of the parent of the category, For example the parent of the "restaurant" category would be "Food and Dining"
primary - If the category is primary or not

A category that tags this listing

group

category

group_id
name

The group to which the category belongs. For example, the category "brunch" might belong to the group "restaurant features"

attributes

location

 

Wraps attribute information

attribute

attributes

attribute_id
name - Part of the attribute's name-value pair
value - Part of the attribute's name-value pair

A single attribute, or name-value pair, that gives further information about this listing

business_hours

location

 

The hours that the business is open, if known

parking

location

 

Parking details

tips

location

 

Wraps the tips for this listing

tip

tips

 

A single tip

tip_name

tip

 

The title of the tip (very short)

tip_text

tip

 

The text of the tip

images

location

 

Wraps information for the associated images

image

images

type - One of WEBSITE_THUMBNAIL (a thumbnail of the listing's own website), or GENERIC_IMAGE (a photo that is part of the listing's slideshow).
attribution_source - Unique identifier of the content provider
attribution_logo - The logo of the content provider (typically an 88 x 33 jpeg)
attribution_text - Name of the content provider, to be displayed in place of, or along side of, the attribution logo

A single image

height

image

 

Height of the image

width

image

 

Width of the image

image_url

image

 

URL of the image

editorials

location

 

Wraps editorial reviews

editorial

editorials

attribution_source - Unique identifier of the content provider
attribution_logo - The logo of the content provider (typically an 88 x 33 jpeg)
attribution_text - Name of the content provider, to be displayed in place of, or along side of, the attribution logo

A single editorial review

editorial_id

editorial

 

The id of the editorial review

editorial_url

editorial

 

The url of the full editorial review

editorial_title

editorial

 

The title of the editorial review

editorial_author

editorial

 

The author of this editorial review

editorial_review

editorial

 

The content of the editorial review, which may be abbreviated

pros

editorial

 

Favorable bullet points written by the review author

cons

editorial

 

Unfavorable bullet points written by the review author

editorial_date

editorial

 

The date the editorial review was written in ISO 8601 format.

review_rating

editorial

 

The rating for the review

helpfulness_total_count

editorial

 

The number of times a review has been marked helpful or unhelpful

helpful_count

editorial

 

The number of times a review has been marked helpful

unhelpful_count

editorial

 

The number of times a review has been marked unhelpful

review_info

location

 

Review statistics

overall_review_rating

review_info

 

The rating for the review (a number between 0 and 10) or NA

total_user_reviews

review_info

 

The number of reviews that have been written for this listing

total_user_reviews_shown

review_info

 

The number of reviews shown in this response (may be less than the total number)

reviews

review_info

 

Collection of all reviews

review

reviews

attribution_source - Unique identifier of the content provider
attribution_logo - The logo of the content provider (typically an 88 x 33 jpeg)
attribution_text - Name of the content provider, to be displayed in place of, or along side of, the attribution logo
attribution_url - The website of the reviews source.

A single review

review_id

review

 

The internal CityGrid id for the review

review_url

review

 

The URL of the review on CityGrid (required for link-back attribution)

review_title

review

 

The title given to the review by its author

review_author

review

 

The name of the user that wrote the review

review_text

review

 

The text of the review

pros

review

 

Favorable bullet points written by the review author

cons

review

 

Unfavorable bullet points written by the review author

review_date

review

 

The date the review was written in ISO 8601 format.

review_rating

review

 

The rating for the review (a number between 0 and 10)

helpfulness_total_count

review

 

The number of times a review has been marked helpful or unhelpful

helpful_count

review

 

The number of times a review has been marked helpful

unhelpful_count

review

 

The number of times a review has been marked unhelpful

review_type

review

 

The type of review. Current types are user_review and editorial_review

geographies

location

 

The geographic regions associated with the place.

geography

geographies

 

A single geography.

id

geography

 

Unique identifier for the specific region.

type

geography

 

A description of the region, one of: city, county, market, neighborhood, postal.code, state).

value

geography

 

The common name for the region. Examples: Venice, CA (neighborhood), Los Angeles, CA (city), Los Angeles, CA Metro (market).

XML Response

The following is an example of an XML response with blank data.

Icon

character data is required to be escaped, so you will likely see the character entities ", &, >, <, and '.

JSON Response

The following is an example of a JSON response with blank data:

If a callback parameter is supplied, the JSON response will be wrapped in a call as follows:

Protocol Buffers Response

Google's Protocol Buffers is a format that can easily be processed by applications written in Java, C++, or Python. To use the protocol buffer format, run the protocol buffer compiler for your language on this proto file. The generated classes can then be used to populate, serialize, and read protocol buffer messages.

See Google's Tutorials for information on how to compile .proto files and use the generated classes.

Impression Url

Places Details provides a basic Places that Pay tracking URL in the response called impression_url. This url contains information about the location and can be used in place of the Javascript implementation of Places that Pay. Publishers intend to utilize this field should append the action_target parameter at the end of the url and send it whenever there is a billable action.

Detail Error Reporting

CityGrid Media provides error codes, rather than error messages. This allows you to customize the text and language for display. If a request can not be completed for any reason, an error document will be returned with a set of mnemonic error codes to help you troubleshoot the error.

Error Codes

A complete list of error codes follows:

Code

Reason

query.overspecified

More than one of listing id, infousa id, and phone was given

query.underspecified

Neither listing id, infousa id, nor phone was given for search

id.illegal

The listing id provided was not in the correct format

customer.only.illegal

The value of the customer_only parameter was illegal

publisher.required

The publisher was not given

listing.not.found

No listing with the given id exists

phone.not.found

No listing with the given phone exists

phone.invalid

The phone number was not valid

client.ip.invalid

The client ip parameter was not supplied or not correct

infousa.id.illegal

The value of the infousa_id parameter was illegal

review.count.illegal

The value of the review_count parameter was illegal

all.results.illegal

The value of the all_results parameter was not either true or false

internal.error

An internal problem with the service has occurred

image.count.illegal

The value of the image_count is not a valid number

image.count.out.of.range

The value of the image_count is a negative

image.size.range.invalid

The value of image_size_min is greater than the image_size_max

image.size.illegal

The value of image_size_min and/or image_size_max do not follow the format specified in the Detail Request

XML Error Response

In the XML response, the error codes are contained within errors and error tags.

Element

Parent Element

Description

errors

 

Root node. A Collection of errors.

error

errors

An error code. See the table of error codes above.

For example, the following request:

returns the following response:

JSON Error Response

In the JSON response, the error codes are values paired with error keys, as part of an errors array.

For example, the following request:

returns the following response:

  • No labels