Granicus Search API - Introduction

Description and Capabilities

The Granicus Search API allows you to query any marker or video from the entire Granicus library, spanning nearly 1,000 government agencies and including over 2 million individual topics or discussions representing over 100 years of total archived video. The API is roughly modeled after the Elastic Search API, which is documented here.

API Keys

The API currently does not require any API key. This may change in the future if usage or abuse begins to cause problems. Please be mindful of the performance of your queries, and try not to run expensive ones too often. If too many expensive queries are run, we will have to institute API keys and throttling. Keys and throttling are a pain. They get in the way of making cool things. We like cool things. Please don't ruin it for everyone by being selfish about resources.

60 Second Quick Start

The API currently only exposes a single endpoint which can be used for searching:

http://search.granicus.com/api/_search

You can also search an individual index, for instance for a city, by using:

http://search.granicus.com/api/sanfrancisco.granicus.com/_search

The easiest searches are done by simply adding ?q=<query> and performing a get. The query can be anything that you would type into the Granicus Search UI. An example search can be performed simply by visiting

http://search.granicus.com/api/_search?q=budget

which returns results for the search term "budget". You can further refine that search to only markers by adding a type field:

http://search.granicus.com/api/_search?q=budget&type=marker

The _search endpoint functions exactly the like the search endpoint in Elastic Search. It returns a JSON response to a JSON query, or if you're lazy a simple GET query with the proper parameters. This makes it extremely easy to interact with using common tools such as cURL or even a simple web browser. There are also many good clients for Elastic Search that should work seamlessly with the Granicus Search API. We have had very good luck performing searches against the API using the tire Ruby Gem, as well as manually POSTing JSON to the API using JavaScript.