FilmMap API =========== The API privides a means to query the FilmMap database. The results are in JSON format. The source comes from the `San Francisco Open Data Portal`_. The API source is based on the data from `Film Locations in San Francisco`_. Here is it's `JSON source`_. As you can see, the source structures information a little differently than this API does. The actors in the original source had attributes like *actor_1, actor_2, ...*. The locations were also interspersed for each entry, breaking the *Don't Repeat Yourself* principle. In addition, duplicate entries were found in the original source. Finally, actors and writers are comma-delimited in a string. This API conveniently puts *actors, writers and locations* in JSON lists so that it's much more convenient to manipulate, and each entry corresponds to a *film* and not a film location. This API is arguably much better structured and more convenient to use, but if you decide to use the original source instead of this one, see the `Socrata API Reference`_ for details on how to structure queries. Options ------- The options are as follows: +-----------+-------------------------------------+-----------------+ | Parameter | Description | Default | +===========+=====================================+=================+ | select | Which columns to return | All columns | +-----------+-------------------------------------+-----------------+ | where | Filter on results to return | All results | +-----------+-------------------------------------+-----------------+ | order | Order to return the results | Ascending order | +-----------+-------------------------------------+-----------------+ | limit | Maximum number of results to return | All results | +-----------+-------------------------------------+-----------------+ *Note: The select clause will always return the title in addition to and selected columns.* Examples -------- Here's an example demonstrating simple usage of a ``where`` parameter: ``http://thawing-inlet-6857.herokuapp.com/api/v1/?where=title=180`` The result *(03-27-14)*:: [{"title": "180", "release_year": 2011, "production_company": "SPI Cinemas", "director": "Jayendra", "distributor": "", "locations": [{"fun_facts": "", "location": "555 Market St."}, {"fun_facts": "", "location": "Epic Roasthouse (399 Embarcadero)"}, {"fun_facts": "", "location": "Mason & California Streets (Nob Hill)"}, {"fun_facts": "", "location": "Justin Herman Plaza"}, {"fun_facts": "", "location": "200 block Market Street"}, {"fun_facts": "", "location": "City Hall"}, {"fun_facts": "", "location": "Polk & Larkin Streets"}, {"fun_facts": "", "location": "Randall Musuem"}], "writers": ["Umarji Anuradha", "Aarthi Sriram", "Suba", "Jayendra"], "actors": ["Nithya Menon", "Priya Anand", "Siddarth"]}] | Note that the ``where`` parameter can return more than one result for more general search terms. | Here's an example of the ``where`` parameter for a more general search term: ``http://thawing-inlet-6857.herokuapp.com/api/v1/?where=title=Night`` The result *(03-27-14)*:: [{"title": "A Night Full of Rain", "release_year": 1978, "production_company": "Liberty Film", "director": "Lina Wertmuller", "distributor": "Warner Bros. Pictures", "locations": [{"fun_facts": "The San Francisco Zodiac Killer of the late 1960s sent his notes and letters to the Chronicle's offices.", "location": "San Francisco Chronicle (901 Mission Street at 15th Street)"}, {"fun_facts": "In 1945 the Fairmont hosted the United Nations Conference on International Organization as delegates arrived to draft a charter for the organization. The U.S. Secretary of State, Edward Stettinus drafted the charter in the hotel's Garden Room.", "location": "Fairmont Hotel (950 Mason Street, Nob Hill)"}, {"fun_facts": "Embarcadero Freeway, which was featured in the film was demolished in 1989 because of structural damage from the 1989 Loma Prieta Earthquake)", "location": "Embarcadero Freeway"}, {"fun_facts": "", "location": "Broadway (North Beach)"}], "writers": ["Lina Wertmuller"], "actors": ["Candice Bergen", "Giancarlo Gianni"]}, {"title": "Forty Days and Forty Nights", "release_year": 2002, "production_company": "Miramax Films", "director": "Michael Lehmann", "distributor": "Miramax Films", "locations": [{"fun_facts": "Established in 1867, Buena Vista Park is the oldest official park in San Francisco.", "location": "The Walden House, Buena Vista Park"}, {"fun_facts": "Francis Ford Coppola allegedly wrote large portions of \"The Godfather\" trilogy in Caf\u00e9 Trieste.", "location": "Caf\u00e9 Trieste (609 Vallejo)"}], "writers": ["Robert Perez"], "actors": ["Josh Hartnett", "Shaynnyn Sossamon"]}, {"title": "Just One Night", "release_year": 2000, "production_company": "Panoptic Pictures", "director": "Alan Jacobs", "distributor": "First Look International", "locations": [{"fun_facts": "Every hour and half-hour, the clock bell atop the Ferry Building chimes portions of the Westminster Quarters.", "location": "Ferry Building"}], "writers": ["Alan Jacobs"], "actors": ["Timothy Hutton", "Maria Grazia Cucinotta"]}, {"title": "Midnight Lace", "release_year": 1960, "production_company": "Arwin Productions", "director": "David Miller", "distributor": "Universal Pictures", "locations": [{"fun_facts": "In 1945 the Fairmont hosted the United Nations Conference on International Organization as delegates arrived to draft a charter for the organization. The U.S. Secretary of State, Edward Stettinus drafted the charter in the hotel's Garden Room.", "location": "Fairmont Hotel (950 Mason Street, Nob Hill)"}], "writers": ["Ivan Geoff"], "actors": ["Rex Harrison", "Doris Day"]}, {"title": "Night of Henna", "release_year": 2005, "production_company": "Zee Films", "director": "Hassan Zee", "distributor": "Illuminare Entertainment", "locations": [], "writers": ["Hassan Zee"], "actors": ["Joyce Carlin", "Nancy Carlin"]}, {"title": "The Nightmare Before Christmas", "release_year": 1993, "production_company": "Touchstone PictureS", "director": "Henry Selick", "distributor": "Buena Vista Pictures", "locations": [], "writers": ["Tim Burton"], "actors": ["Danny Elfman", "Catherine O'Hara"]}] Note that the previous query returned *6 results*. Suppose you only wanted to return *2 results*. The following is a refined query using the ``limit`` parameter demonstrating how to return *2 results* from the query: ``http://thawing-inlet-6857.herokuapp.com/api/v1/?where=title=Night&limit=2`` The result *(03-27-14)*:: [{"title": "A Night Full of Rain", "release_year": 1978, "production_company": "Liberty Film", "director": "Lina Wertmuller", "distributor": "Warner Bros. Pictures", "locations": [{"fun_facts": "The San Francisco Zodiac Killer of the late 1960s sent his notes and letters to the Chronicle's offices.", "location": "San Francisco Chronicle (901 Mission Street at 15th Street)"}, {"fun_facts": "In 1945 the Fairmont hosted the United Nations Conference on International Organization as delegates arrived to draft a charter for the organization. The U.S. Secretary of State, Edward Stettinus drafted the charter in the hotel's Garden Room.", "location": "Fairmont Hotel (950 Mason Street, Nob Hill)"}, {"fun_facts": "Embarcadero Freeway, which was featured in the film was demolished in 1989 because of structural damage from the 1989 Loma Prieta Earthquake)", "location": "Embarcadero Freeway"}, {"fun_facts": "", "location": "Broadway (North Beach)"}], "writers": ["Lina Wertmuller"], "actors": ["Candice Bergen", "Giancarlo Gianni"]}, {"title": "Forty Days and Forty Nights", "release_year": 2002, "production_company": "Miramax Films", "director": "Michael Lehmann", "distributor": "Miramax Films", "locations": [{"fun_facts": "Established in 1867, Buena Vista Park is the oldest official park in San Francisco.", "location": "The Walden House, Buena Vista Park"}, {"fun_facts": "Francis Ford Coppola allegedly wrote large portions of \"The Godfather\" trilogy in Caf\u00e9 Trieste.", "location": "Caf\u00e9 Trieste (609 Vallejo)"}], "writers": ["Robert Perez"], "actors": ["Josh Hartnett", "Shaynnyn Sossamon"]}] The ``limit`` clause in the previous example returned the first two results matching the title '*Night*'. Suppose you wanted to return the last two results matching that title. You can use the ``order`` parameter to order the results in descending order, and then use the ``limit`` clause to grab the first two entries. To order an attribute in descending order, prefix the attribute you want to order by with a *-*. This will return the last two entries. Here is the example: ``http://thawing-inlet-6857.herokuapp.com/api/v1/?where=title=Night&order=-title&limit=2`` The result *(03-27-14)*:: [{"title": "The Nightmare Before Christmas", "release_year": 1993, "production_company": "Touchstone PictureS", "director": "Henry Selick", "distributor": "Buena Vista Pictures", "locations": [], "writers": ["Tim Burton"], "actors": ["Danny Elfman", "Catherine O'Hara"]}, {"title": "Night of Henna", "release_year": 2005, "production_company": "Zee Films", "director": "Hassan Zee", "distributor": "Illuminare Entertainment", "locations": [], "writers": ["Hassan Zee"], "actors": ["Joyce Carlin", "Nancy Carlin"]}] Finally, let's say that you don't need all of those columns. Suppose you only want the *title* and the *actors*. You can use the ``select`` parameter to select *actors*: ``http://thawing-inlet-6857.herokuapp.com/api/v1/?select=actors&where=title=Night&order=-title&limit=2`` The result *(03-27-14)*:: [{"title": "The Nightmare Before Christmas", "actors": ["Danny Elfman", "Catherine O'Hara"]}, {"title": "Night of Henna", "actors": ["Joyce Carlin", "Nancy Carlin"]}] .. _San Francisco Open Data Portal: http://data.sfgov.org .. _Film Locations in San Francisco: https://data.sfgov.org/Arts-Culture-and-Recreation-/Film-Locations-in-San-Francisco/yitu-d5am .. _JSON source: https://data.sfgov.org/resource/yitu-d5am.json .. _Socrata API Reference: http://beta.dev.socrata.com/docs/queries.html