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 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.
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, and returns returning one or more items that match the search, 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 that particular 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.
In addition to using the Place IDs returned from Places Search, you can query the Places Detail API using the Place ID supplied by from one of the many sources of data merged and 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 companies' data source are supported:
CityGrid Public Id
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.