You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Nested Year Timelines is a hierarchical timeline visualization that supports exploring large sets of news article retrieved from the [New York Times Article Search API](http://developer.nytimes.com/docs/read/article_search_api_v2).
Nested Year Timelines is a hierarchical timeline visualization that supports exploring large sets of news article retrieved from the [New York Times Article Search API](http://developer.nytimes.com/docs/read/article_search_api_v2).
9
+
## Live Demo
8
10
9
-
Most importantly, you should go play with it at [keynotesavant.com](http://keynotesavant.com/). (Be gentle and patient with that server, please!)
11
+
You should definitely go play with Nested Year Timelines at [keynotesavant.com](http://keynotesavant.com/). (Be gentle and patient with that server, please!)
10
12
11
13
## Credits
12
14
13
15
* Design Concept: **Michael and Joe**
16
+
* Data: [The New York Times](http://developer.nytimes.com/)
14
17
* Prototype Implementation: **Michael**
15
18
* New York Times API Wrangling and Python-Whispering: **Joe**
16
19
* Spit-Shining: **Joe**
@@ -23,4 +26,75 @@ Most importantly, you should go play with it at [keynotesavant.com](http://keyno
23
26
24
27
Again, check out the live version of NYT at [keynotesavant.com](http://keynotesavant.com/) if you haven't already.
25
28
26
-
If you're about to clone this repository and
29
+
If you're about to clone this repository and try to get this working on your own, keep reading.
30
+
31
+
### System Requirements
32
+
33
+
This is a Python job, so you'll need the following software to run Nested Year Timelines:
34
+
35
+
*[Python 2.7.5](http://python.org) (probably doesn't work with Python 3)
36
+
*[Flask 0.10](http://flask.pocoo.org)
37
+
*[Requests: HTTP for Humans](http://docs.python-requests.org/en/latest/)
38
+
* Maybe some other fourth thing (Python will tell you, I promise)
39
+
40
+
### Configure the App with config.py
41
+
42
+
Once you've cloned the repository, check out the `flask` folder. Inside you'll find `config_example.py`, which you should **duplicate** and rename `config.py`. Open it up and you'll see something like this:
43
+
44
+
class Config(object):
45
+
DEBUG = False
46
+
# NYT Article Search API Key
47
+
# Request a key at http://developer.nytimes.com
48
+
SEARCH_API_KEY = "PASTE_API_KEY_HERE"
49
+
CACHE_ROOT = os.path.join(
50
+
os.path.dirname(os.path.realpath(__file__)),
51
+
"static",
52
+
"cache"
53
+
)
54
+
ARTICLE_SEARCH_ROOT = os.path.join(
55
+
CACHE_ROOT,
56
+
"ArticleSearch"
57
+
)
58
+
QUERY_CACHE_PATH = os.path.join(
59
+
CACHE_ROOT,
60
+
"queries.json"
61
+
)
62
+
63
+
64
+
class DevelopmentConfig(Config):
65
+
DEBUG = True
66
+
67
+
### Request an Article Search API Key from The New York Times
68
+
69
+
Visit [developer.nytimes.com](http://developer.nytimes.com), create a user account, and [register your application](http://developer.nytimes.com/apps/register) for use with the Article Search API.
70
+
71
+
NYT will give you an API key, which you should paste into `config.py` to set the value of `SEARCH_API_KEY` to a valid API key string.
72
+
73
+
### Run the Flask Server
74
+
75
+
If you're just on your local machine, invoke `python` on the command line to start the Flask web server on [http://localhost:5000](http://localhost:5000):
76
+
77
+
$ cd path/to/repo
78
+
$ cd flask
79
+
$ python app.py
80
+
Loaded cached queries from disk.
81
+
* Running on http://127.0.0.1:5000/
82
+
83
+
### Appendix: Cache Files and Folders
84
+
85
+
Check out `flask/static/cache/` for three (count 'em, three) types of cache files:
86
+
87
+
1.`queries.json`, which lists recent queries (for which there may exist cached data)
88
+
2. In the `ArticleSearch` folder, `61c5cce1ba03475e.json` (or something like that) is a cached JSON file containing all the NYT Article Search API results for a certain query.
89
+
* Which query does a certain file represent, you ask? Good question. There's a rudimentary caching scheme in place that uses the search query value to generate a file name, so your guess is as good as mine. Check out the function `nyt_api.ArticleSearch.get_hash_for_query` for more on how those file names are generated.
90
+
* I can tell you that `61c5cce1ba03475e.json` contains the cached results for the query `fq=persons:("Obama, Barack")`, however.
91
+
* These cache files take a long time to generate since we have to retrieve however many thousands of article results from the NYT Article Search API to create them. I'd let them stick around if you can spare the megabytes.
92
+
3. In the `ArticleSearch` folder, `64d2ae7086249faf_reduce_by_year_and_month_with_multimedia.json` is a cache file containing the reduced data set that actually gets loaded into Nested Year Timelines. **These are both smaller and easier to regenerate,** so get rid of them whenever you want.
93
+
94
+
### Uh, That's It
95
+
96
+
Things should be up and running. Don't forget to have fun!
0 commit comments