Places API
- Former user (Deleted)
- Former user (Deleted)
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.
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
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:
https://api.citygridmedia.com/content/places/v2/search/where
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 |
| movie | 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 |
|
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 | 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 |
|
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 | 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 |
| 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. |
publisher | The publisher code that identifies you. | Yes |
|
| acme |
|
format | The desired format for the results | No | json | xml | json | json = javascript object notation |
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 | true | 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 |
| Turning on histograms can affect performance. More information is provided below. |
| call_id | Iddentify 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_refinement | Restricts search to listings containing specific tags. | No | Tag(s) separated by comma. | haircut,hair dye | This is for getting results that match ALL tags. To search for results that match ANY tags use the what parameter | |
| site | Restricts search to listings at a specific location | No | Integer | 12345 | Site 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.
Usage | URL |
|---|---|
Find movie theaters in zip code 90045 | |
Find Italian restaurants in Chicago using placement “sec-5” | |
Find hotels in Boston, viewing results 1-5 in alphabetical order | |
Find pharmacies near the L.A. County Music Center, sorted by distance |
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.
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 | Highest relevance first |
|
Neighborhoods | Hollywood (Los Angeles, CA) | Highest relevance first |
|
Zip Codes | 90210 | Highest relevance first |
|
Metro Areas | Los Angeles, CA 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
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:
https://api.citygridmedia.com/content/places/v2/search/latlon
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 |
| movie | 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 | 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 | 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 |
|
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 |
| 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. |
publisher | The publisher code that identifies you. | Yes |
|
| acme |
|
format | The desired format for the results | No | json | xml | json | json = javascript object notation |
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 | true |
|
histograms | Provide information on how many listings are in given groups and categories. | No | true | false |
| Turning on histograms can affect performance. More information is provided below. |
| call_id | Identify 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_refinement | Restricts search to listings containing specific tags. | No | Tag(s) separated by comma. | haircut,hair dye | This is for getting results that match ALL tags. To search for results that match ANY tags use the what parameter | |
| site | Restricts search to listings at a specific location | No | Integer | 12345 | Site 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.) |
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.
Usage | URL |
|---|---|
Find movie theaters within 5 miles of latitude 34.03N, longitude118.28W |
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:
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.
Usage
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.
Usage
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 XML, JSON, 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 | Metadata regarding the search results. |
uri | results |
| Request URL processed. |
| call_id | results | 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.
<?xml version="1.0" encoding="utf-8"?>
<results rpp="" page="" last_hit="" first_hit="" total_hits=""
query_id="">
<uri></uri>
<did_you_mean />
<regions>
<region type="">
<name></name>
<latitude></latitude>
<longitude></longitude>
<default_radius></default_radius>
</region>
</regions>
<locations>
<location id="">
<featured></featured>
<name></name>
<address>
<street></street>
<city></city>
<state></state>
<postal_code></postal_code>
</address>
<neighborhood></neighborhood>
<latitude></latitude>
<longitude></longitude>
<distance />
<image></image>
<phone_number></phone_number>
<fax_number />
<rating></rating>
<tagline />
<profile></profile>
<website />
<has_video></has_video>
<has_offers></has_offers>
<offers />
<user_review_count></user_review_count>
<sample_categories></sample_categories>
<impression_id></impression_id>
<expansion />
<tags>
<tag id=""></tag>
</tags>
<public_id/>
</location>
</locations>
<histograms>
<histogram name="">
<items>
<item name="" count=""></item>
</items>
</histogram>
</histograms>
</results>
JSON Response
The following is an example of a JSON response:
{
"results": {
"query_id": "",
"uri": "",
"first_hit": 1,
"last_hit": 20,
"total_hits": 163,
"page": 1,
"rpp": 20,
"did_you_mean": "",
"regions": [
{
"type": "",
"name": "",
"latitude": 34.10652,
"longitude": -118.411509,
"default_radius": 22.45
}
],
"locations": [
{
"id": 3663784,
"featured": false,
"name": "",
"address": {
"street": "",
"city": "",
"state": "",
"postal_code": ""
},
"neighborhood": "",
"latitude": 41.8902,
"longitude": -87.6338,
"distance": "",
"image": "",
"phone_number": "",
"fax_number": "",
"rating": 8,
"tagline": "",
"profile": "",
"website": "",
"has_video": false,
"has_offers": false,
"offers": "",
"user_review_count": 265,
"sample_categories": "",
"impression_id": "",
"expansion": {
"count": "",
"uri": ""
},
"tags": [
{
"id": "",
"name: ""
},
"public_id": ""
]
}
],
"histograms": [
{
"name": "Categories",
"items": [
{
"count": 137,
"name": "",
"uri": "",
"tag_ids": [
{
"tag_id": 10015
}
]
}
]
}
]
}
}
Notes
If a callback parameter is supplied, the JSON response will be wrapped in a call as follows:
callback_name({"results": {...}})
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:
<did_you_mean>computer parts</did_you_mean>
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
where=vail&what=candy
might produce a result as follows:
<results>
...
<regions>
<region type="city">
<name>Vail, CO</name>
<latitude>39.6388</latitude>
<longitude>-106.3624</longitude>
<default_radius>2.130000</default_radius>
</region>
<region type="city">
<name>Vail, IA</name>
<latitude>42.0598</latitude>
<longitude>-95.2004</longitude>
<default_radius>0.740000</default_radius>
</region>
<region type="neighborhood">
<name>Vail Vista Estates, AZ</name>
<latitude>32.0321</latitude>
<longitude>-110.6999</longitude>
<default_radius>0.350000</default_radius>
</region>
<region type="neighborhood">
<name>Vail Ranch, AZ</name>
<latitude>32.0512</latitude>
<longitude>-110.6870</longitude>
<default_radius>0.320000</default_radius>
</region>
<region type="neighborhood">
<name>Old Vail Village (Tucson, AZ)</name>
<latitude>32.0436</latitude>
<longitude>-110.7114</longitude>
<default_radius>0.270000</default_radius>
</region>
</regions>
...
</results>
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.
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
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:
<histograms>
<histogram name="Cuisine">
<items>
<item name="Thai" count="4">
<url>http://api.citygridmedia.com/content/places/v2/search/where?what=food&tag=11319&where=90004&radius=0.7&publisher=xyz</url>
<tag_ids>
<tag_id>11319</tag_id>
</tag_ids>
</item>
<item name="Chinese" count="3">
<url>http://api.citygridmedia.com/content/places/v2/search/where?what=food&tag=11252&where=90004&radius=0.7&publisher=xyz</url>
<tag_ids>
<tag_id>11252</tag_id>
</tag_ids>
</item>
<item name="Mexican" count="1">
<url>http://api.citygridmedia.com/content/places/v2/search/where?what=food&tag=11208&where=90004&radius=0.7&publisher=xyz</url>
<tag_ids>
<tag_id>11208</tag_id>
</tag_ids>
</item>
</items>
</histogram>
<histogram name="Categories">
<items>
<item name="Ice Cream Parlors" count="1">
<url>http://api.citygridmedia.com/content/places/v2/search/where?what=food&tag=1730&where=90004&radius=0.7&publisher=xyz</url>
<tag_ids>
<tag_id>1730</tag_id>
</tag_ids>
</item>
<item name="Grocery Stores" count="20">
<url>http://api.citygridmedia.com/content/places/v2/search/where?what=food&tag=1712&where=90004&radius=0.7&publisher=xyz</url>
<tag_ids>
<tag_id>1712</tag_id>
</tag_ids>
</item>
<item name="Coffeehouses" count="2">
<url>http://api.citygridmedia.com/content/places/v2/search/where?what=food&tag=1726&where=90004&radius=0.7&publisher=xyz</url>
<tag_ids>
<tag_id>1726</tag_id>
</tag_ids>
</item>
<item name="Restaurants" count="26">
<url>http://api.citygridmedia.com/content/places/v2/search/where?what=food&tag=1722&where=90004&radius=0.7&publisher=xyz</url>
<tag_ids>
<tag_id>1722</tag_id>
</tag_ids>
</item>
</items>
</histogram>
<histogram name="Health Food Store Products">
<items>
<item name="Vitamins" count="2">
<url>http://api.citygridmedia.com/content/places/v2/search/where?what=food&tag=11164&where=90004&radius=0.7&publisher=xyz</url>
<tag_ids>
<tag_id>11164</tag_id>
</tag_ids>
</item>
</items>
</histogram>
</histograms>
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:
https://api.citygridmedia.com/content/places/v2/search/where?what=food&where=los+angeles,ca
returns the following response:
<?xml version="1.0" encoding="UTF-8"?>
<errors>
<error>publisher.required</error>
</errors>
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:
https://api.citygridmedia.com/content/places/v2/search/where?where=lax&page=q&lon=2&format=json
returns the following response:
{
"errors": [
{
"error": "page.illegal"
},
{
"error": "query.underspecified"
},
{
"error": "geography.overspecified"
},
{
"error": "publisher.required"
}
]
}
Places Detail
The Places Details API provides programmatic access to CityGrid's local listings data, including businesses and events.
Detail HTTPS Endpoint
https://api.citygridmedia.com/content/places/v2/detail
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 |
| cg | If you are switching from the deprecated parameters to the new parameters id and id_type, here is the corresponding id type mappings: | |||
(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 | 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 | 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 | 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 | json |
| ||
callback | The name of (your own) JavaScript function that you would like to wrap your JSON response. | No |
|
| display |
| ||
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 | 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 | 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. |
Arguments must be properly URL-encoded (spaces as %20 or +, ampersands as %26, and so on).
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 | |
Find the place with infousa ID of 412275828 and client IP of 123.124.123.124 | |
Find the place with phone 323-256-9617 and client IP of 123.124.123.124 | |
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 | |
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 |
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_links | urls | List of custom urls provided by a merchant - these are the clicks they are most interested in. | |
| type | custom_link | The action_target the link corresponds to. A full list is available under Places That Pay | |
| url | custom_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_text | custom_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 | 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 | 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 | A category that tags this listing |
group | category | group_id | 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 | 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). | 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 | 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 | 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: |
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.
character data is required to be escaped, so you will likely see the character entities ", &, >, <, and '.
<locations>
<location>
<id></id>
<reference_id></reference_id>
<impression_id></impression_id>
<display_ad></display_ad>
<infousa_id></infousa_id>
<name></name>
<teaser></teaser>
<address>
<street></street>
<delivery_point />
<city></city>
<state></state>
<postal_code></postal_code>
<cross_street />
<latitude />
<longitude />
</address>
<contact_info>
<display_phone></display_phone>
<display_url></display_url>
<social_media>
<twitter_username>
<image_icon></image_icon>
<text></text>
<url></url>
</twitter_username>
<facebook_fanpage>
<image_icon></image_icon>
<text></text>
<url></url>
</facebook_fanpage>
</social_media>
</contact_info>
<markets>
<market></market>
<market></market>
</markets>
<neighborhoods>
<neighborhood></neighborhood>
<neighborhood></neighborhood>
</neighborhoods>
<urls>
<profile_url />
<reviews_url />
<video_url />
<website_url />
<menu_url />
<reservation_url />
<map_url />
<send_to_friend_url />
<email_link />
<custom_link_1 />
<custom_link_2 />
<custom_link_3 type="" />
<custom_link_4 type="" />
<custom_links>
<custom_link>
<type>online_enrollment</type>
<url>http://api.citygridmedia.com/rbl/content/places/v2/click?q=stcikV14e35E2qZXkN4</url>
<display_text>Enroll!</display_text>
</custom_link>
</custom_links>
</urls>
<impression_url />
<customer_content>
<customer_message attribution_text="" attribution_logo="" attribution_source=""></customer_message>
<bullets>
<bullet></bullet>
<bullet></bullet>
</bullets>
<customer_message_url></customer_message_url>
</customer_content>
<offers>
<offer attribution_logo="" attribution_source="" attribution_text="" attribution_url="">
<offer_name></offer_name>
<offer_text></offer_text>
<offer_description></offer_description>
<offer_url></offer_url>
<offer_expiration_date></offer_expiration_date>
</offer>
</offers>
<categories>
<category parent="" parent_id="" name="" name_id="" primary="">
<groups>
<group name="" group_id=""/>
</groups>
</category>
</categories>
<attributes>
<attribute value="" name="" attribute_id=""/>
</attributes>
<business_hours />
<parking />
<tips>
<tip>
<tip_name />
<tip_text />
</tip>
</tips>
<images>
<image attribution_text="" attribution_logo="" attribution_source="" type="">
<height/>
<width/>
<image_url/>
</image>
</images>
<editorials>
<editorial attribution_text="" attribution_logo="" attribution_source="">
<editorial_id/>
<editorial_url/>
<editorial_title/>
<editorial_author/>
<editorial_review/>
<pros/>
<cons/>
<editorial_date/>
<review_rating/>
<helpfulness_total_count/>
<helpful_count/>
<unhelpful_count/>
</editorial>
</editorials>
<review_info>
<overall_review_rating />
<total_user_reviews />
<total_user_reviews_shown />
<reviews>
<review attribution_text="" attribution_logo="" attribution_source="">
<review_id />
<review_url />
<review_title />
<review_author />
<review_text />
<pros />
<cons />
<review_date />
<review_rating />
<helpfulness_total_count />
<helpful_count />
<unhelpful_count />
<review_type />
</review>
</reviews>
</review_info>
<years_in_business/>
<last_update_time/>
<public_id/>
<business_operation_status/>
<geographies>
<geography type="" id=""></geography>
</geographies>
</location>
</locations>
JSON Response
The following is an example of a JSON response with blank data:
{
"locations" : [
{
"id" : 1,
"reference_id" : "",
"impression_id" : "",
"display_ad" : true,
"infousa_id" : 1,
"name" : "",
"teaser" : "",
"address" : {
"street" : "",
"delivery_point" : "",
"city" : "",
"state" : "",
"postal_code" : "",
"cross_street" : "",
"latitude" : 1.0,
"longitude" : -1.0
},
"contact_info" : {
"display_phone" : "",
"display_url" : "",
"social_media" : {
"twitter_username" : {
"image_icon" : "",
"text" : "",
"url" : ""
},
"facebook_fanpage" : {
"image_icon" : "",
"text" : "",
"url" : ""
}
}
},
"markets" : [
""
],
"neighborhoods" : [
""
],
"urls" : {
"profile_url" : "",
"reviews_url" : "",
"video_url" : "",
"website_url" : "",
"menu_url" : "",
"reservation_url" : "",
"map_url" : "",
"send_to_friend_url" : "",
"email_link" : "",
"custom_link_1" : "",
"custom_link_2" : "",
"custom_link_3" : {
"type" : "",
"source" :""
},
"custom_link_4" : {
"type" : "",
"source" : ""
},
custom_links: [
type: "free_estimate",
url: "http://api.citygridmedia.com/rbl/content/places/v2/click?q=lakejr1po34urfwaeosdi",
display_text: "Request a FREE estimate"
]
},
"impression_url" : "",
"customer_content" : {
"customer_message" : {
"attribution_source" : "",
"attribution_logo" : "",
"attribution_text" : "",
"value" : ""
},
"bullets" : [
""
],
"customer_message_url" : ""
},
"offers" : [
{
"offer_name" : "",
"offer_text" : "",
"offer_description" : "",
"offer_url" : "",
"offer_expiration_date" : "",
"attribution_source" : "",
"attribution_logo" : "",
"attribution_text" : "",
"attribution_url" : ""
}
],
"categories" : [
{
"name_id" : 1,
"name" : "",
"parent_id" : 1,
"parent" : "",
"primary": "",
"groups" : [
{
"group_id" : 1,
"name" : ""
}
]
}
],
"attributes" : [
{
"attribute_id" : 1,
"name" : "",
"value" : ""
}
],
"business_hours" : "",
"parking" : "",
"tips" : [
{
"tip_name" : "",
"tip_text" : ""
}
],
"images" : [
{
"type" : null,
"height" : null,
"width" : null,
"image_url" : null,
"attribution_source" : "",
"attribution_logo" : "",
"attribution_text" : ""
}
],
"editorials" : [
{
"attribution_source" : "",
"attribution_logo" : "",
"attribution_text" : "",
"editorial_id" : 1,
"editorial_url" : "",
"editorial_title" : "",
"editorial_author" : "",
"editorial_review" : "",
"pros" : "",
"cons" : "",
"editorial_date" : "",
"review_rating" : 2.0,
"helpfulness_total_count" : 1,
"helpful_count" : 1,
"unhelpful_count" : 1
}
],
"years_in_business" : "",
"last_update_time" : "",
"public_id" : "",
"business_operation_status" : "",
"review_info" : {
"overall_review_rating" : 2.0,
"total_user_reviews" : 1,
"total_user_reviews_shown" : 1,
"reviews" : [
{
"attribution_source" : "",
"attribution_logo" : "",
"attribution_text" : "",
"review_id" : 1,
"review_url" : "",
"review_title" : "",
"review_author" : "",
"review_text" : "",
"pros" : "",
"cons" : "",
"review_date" : "",
"review_rating" : 2.0,
"helpfulness_total_count" : 1,
"helpful_count" : 1,
"unhelpful_count" : 1,
"review_type" : ""
}
]
},
"geographies": [
{
"id": "",
"value": "",
"type": ""
}
]
}
]
}
If a callback parameter is supplied, the JSON response will be wrapped in a call as follows:
callback_name({"locations": [...]})
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:
https://api.citygridmedia.com/content/places/v2/detail?listing_id=joes+pizza
returns the following response:
<errors> <error>id.illegal</error> <error>publisher.required</error> <error>query.underspecified</error> <error>client.ip.invalid</error> </errors>
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:
https://api.citygridmedia.com/content/places/v2/detail?listing_id=2&publisher=sam&format=json
returns the following response:
{
"errors": [
{
"error": "client.ip.invalid"
}
]
}