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.
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.
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"]}]
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"]}]