...
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
Expand | ||
---|---|---|
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
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.
...
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 HTTP HTTPS GET:
Code Block | ||||
---|---|---|---|---|
| ||||
httphttps://api.citygridmedia.com/content/places/v2/search/where |
...
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 |
...
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.
...
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 HTTP HTTPS GET:
Code Block | ||||
---|---|---|---|---|
| ||||
httphttps://api.citygridmedia.com/content/places/v2/search/latlon |
...
Usage | URL |
---|---|
Find movie theaters within 5 miles of latitude 34.03N, longitude118.28W |
...
The point-radius search returns listings in a region with the specified radius. To use this search, specify the lat, lon, and radius parameters.
...
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.
...
For example, the following request:
Code Block | ||||
---|---|---|---|---|
| ||||
httphttps://api.citygridmedia.com/content/places/v2/search/where?what=food&where=los+angeles,ca |
...
For example, the following request:
Code Block | ||||
---|---|---|---|---|
| ||||
httphttps://api.citygridmedia.com/content/places/v2/search/where?where=lax&page=q&lon=2&format=json |
...
The Places Details API provides programmatic access to CityGrid's local listings data, including businesses and events.
Detail
...
HTTPS Endpoint
Code Block | ||||
---|---|---|---|---|
| ||||
httphttps://api.citygridmedia.com/content/places/v2/detail |
...
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 |
...
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. | |
impression_url | 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). |
...
Code Block | ||||
---|---|---|---|---|
| ||||
<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> <custom_link_3 type="" /><display_text>Enroll!</display_text> <custom_link_4 type="" /></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> |
...
Code Block | ||||
---|---|---|---|---|
| ||||
{ "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": "" } ] } ] } |
...
For example, the following request:
Code Block | ||||
---|---|---|---|---|
| ||||
httphttps://api.citygridmedia.com/content/places/v2/detail?listing_id=joes+pizza |
...
For example, the following request:
Code Block | ||||
---|---|---|---|---|
| ||||
httphttps://api.citygridmedia.com/content/places/v2/detail?listing_id=2&publisher=sam&format=json |
...