Content by CityGrid

Introduction

Content by CityGrid is an API suite providing local content for over 18 million businesses. As a CityGrid publisher, you can easily access this information from within your applications, giving your users the ability to easily find and learn about local places.

The suite is comprised of three Content APIs:

• The Places API provides functionality for information on local businesses, including search, detail, user content submission, and predictive text.
• The Offers API provides coupons and special offers from businesses based on geography and category.
• The Reviews API provides access to customer reviews for businesses selected by id or by geography or category.

Key Concepts

Search and Detail

Both the Places and Offers APIs provide search and detail endpoints. The search endpoint allows you to query based on information such as category and geographic location, returning one or more results each with a small amount of information suitable for creating a convenient search result display. Each result contains an ID that you can use in a detail query. When the ID is passed to the detail endpoint, detailed information about the place or offer is returned.

Search and detail endpoints can be used together in several ways. For example, an application could show a map with icons at the locations of local coffee shops by using the Places Search endpoint (which returns latitudes and longitudes). When an end user clicks an icon, a Places Detail query can retrieve detailed information on the selected coffee shop. In addition, a user could search for offers within a given category (e.g., movies) and a given municipality (e.g., Los Angeles) by using the Offers Search endpoint. When a user selects an offer, the application queries the Offers Detail endpoint to display the details of that offer, including the expiration date and redemption code.

Place IDs

In addition to using the Place IDs returned from Places Search, you can query the Places Detail API using the ID from one of the many sources of data aggregated by CityGrid. (This functionality is not yet supported in other APIs.) When querying by ID, supply the source of the ID in the id_type parameter. Place IDs from the following source are supported:

Tags

CityGrid helps your users find local places by assigning to each place one or more tags. Some tags describe a business (such as Restaurant, Bookstore, or Auto Repair) while others identify services or products offered by the business or even generic business attributes (such as Patio Dining, Open 24 hours, Valet Parking, or American Express). Tags are preferred to a rigid, hierarchical, category-only taxonomy for places; see Clay Shirky's article on Internet Ontolgoy for details.

Tags provide several benefits to publishers:

• Tags allow a level of indirection between keywords and places. By mapping certain search terms to tags, it is not necessary to store, in the search index, the same (possibly large) set keywords with every one of the thousands of places that might share a tag.
• Tags make it easier to define sections or themes: it is easier to define sections as collections of tags than as collections of places. (Common themes that you can define with tags include "Valentine's Day," "Thanksgiving", or "Weekend Getways.")
• Tags provide a way for users to refine or expand search results.
• Tags provide a simpler means to find related places. For example, one can define relationships between tags that can link cars to, say, car insurance.

The taxonomy is subject to change at any time; new tags may be added or removed, and parent-child relationships may be adjusted. Tags are published both in list format and tree format, and are updated on a weekly basis. Please refer to the latest files at all times to ensure your applications work as expected.

Geographies

Places are associated to one or more geographies so that users can find businesses in a specific location. Geographies are mapped to physical area and have different types:

• Neighborhood (an area within a city)
• 5 digits zip code
• City
• Market (a DMA)

You can find a list of our neighborhoods, cities and markets in json format here.

It contains the following fields:

Note that geographies can change over time, the file linked above is updated on a weekly basis.