Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 72 lines (41 sloc) 4.482 kb
b653e829 » dwillis
2011-12-13 obligatory ascii art
1 .-----. _ .-. .-. _
2 `-. .-':_; : :.-.: ::_;
3 : : .-.,-.,-.,-. .--. .--. : :: :: :.-..--. .--.
4 : : : :: ,. ,. :' '_.'`._-.' : `' `' ;: :: ..'' '_.'
5 :_; :_;:_;:_;:_;`.__.'`.__.' `.,`.,' :_;:_; `.__.
4accf6c0 » dwillis
2011-12-13 added README and LICENSE
6
7 Times Wire is a Ruby gem for interacting with The New York Times Newswire API (http://developer.nytimes.com/docs/read/times_newswire_api), which provides an up-to-the-minute stream of articles and blog posts published on NYTimes.com and The International Herald-Tribune.
8
9 == News
10
7619b1a8 » dwillis
2013-05-03 updated docs for 0.9
11 * May 3, 2013: Version 0.9.0 released, added Item.url method and tested under 1.9.3.
9995e256 » dwillis
2011-12-16 updated for 0.8.0
12 * Dec. 16, 2011: Version 0.8.0 released, Item returns DateTime objects instead of Dates.
fcb88a78 » dwillis
2011-12-14 updated README for version 0.7.0
13 * Dec. 15, 2011: Version 0.7.0 released, adding support for retrieving list of sections.
8f364883 » dwillis
2011-12-14 updated readme
14 * Dec. 14, 2011: Version 0.6.0 released, with support for related URLs and blog name attributes.
4accf6c0 » dwillis
2011-12-13 added README and LICENSE
15 * Dec. 13, 2011: Version 0.5.0 released.
16
17 == Installation
18
19 Install Times Wire as a gem:
20
21 gem install times_wire
22
23 For use in a Rails 3 application, put the following in your Gemfile:
24
7619b1a8 » dwillis
2013-05-03 updated docs for 0.9
25 gem "times_wire", "~> 0.9.0"
4accf6c0 » dwillis
2011-12-13 added README and LICENSE
26
7619b1a8 » dwillis
2013-05-03 updated docs for 0.9
27 then issue the 'bundle install' command. Times Wire has been tested under Ruby 1.8.7 and 1.9.3.
4accf6c0 » dwillis
2011-12-13 added README and LICENSE
28
29 == Getting Started
30
31 You'll need an API Key from The New York Times Developer Network (http://developer.nytimes.com/). You can set your key as an environment variable (handy for running the test suite) or set it within a script or app:
32
33 TimesWire::Base.api_key = API_KEY
7619b1a8 » dwillis
2013-05-03 updated docs for 0.9
34
35 To retrieve details for a single URL, pass it in:
36
37 @item = Item.url("http://www.nytimes.com/2013/05/04/business/economy/us-adds-165000-jobs-in-april.html")
d3a46cb1 » dwillis
2013-05-03 cleaning up
38 => #<TimesWire::Item:0x1014b2088 @blog_name=nil, @created_date=#<DateTime: 212234344421/86400,-1/6,2299161>, @byline="By NELSON D. SCHWARTZ", @org_facets="", @section="Business Day", @kicker="", @updated_date=#<DateTime: 13264647209/5400,-1/6,2299161>, @related_urls=nil, @url="http://www.nytimes.com/2013/05/04/business/economy/us-adds-165000-jobs-in-april.html", @des_facets=["Labor and Jobs", "United States Economy"], @material_type_facet="News", @source="The New York Times", @geo_facets="", @abstract="The economy in April added 165,000 jobs, slightly more than expected, and the Labor Department sharply revised upward its estimates for job creation in the previous two months.", @multimedia=[{"height"=>75, "url"=>"http://graphics8.nytimes.com/images/2013/05/04/business/economy/04jobs/04jobs-thumbStandard.jpg", "subtype"=>"photo", "width"=>75, "format"=>"Standard Thumbnail", "copyright"=>"Spencer Platt/Getty Images", "caption"=>"Job candidates waited to meet with employers at a job and internship fair in New York last week.", "type"=>"image"}], @published_date=#<DateTime: 7369250/3,-1/6,2299161>, @per_facets="", @item_type="Article", @title="Jobs Data Ease Fears of Sharp Slowdown in U.S. Economy", @subheadline="">
4accf6c0 » dwillis
2011-12-13 added README and LICENSE
39
40 Times Wire allows users to retrieve news items by source ('nyt', 'iht' or 'all'), by section (such as 'world', 'u.s.', 'sports') or by NYTimes.com blog names ("The Caucus", "FiveThirtyEight" or "At War", for example). Building a request is easy. To retrieve the latest items from The New York Times:
41
42 @items = Item.latest('nyt')
43
44 By default, 20 items are returned, but you may change the limit in any request:
45
46 @items = Item.latest('iht', 15)
47
fcb88a78 » dwillis
2011-12-14 updated README for version 0.7.0
48 Limiting the items retrieved to a section of The Times is easy, too. A list of sections supported by the News Wire API can be retrieved as follows:
49
50 @sections = Section.all
51
52 A section name can then be passed as an argument to retrieve items from that section:
4accf6c0 » dwillis
2011-12-13 added README and LICENSE
53
54 @items = Item.section('nyt', 'world')
55
56 Retrieving items from a single Times blog is similar:
57
58 @items = Item.blog_name('nyt', 'u.s.', 'The Caucus')
59
3ff19f05 » dwillis
2011-12-14 added support for related urls and blog name attributes
60 Items from the Newswire API have mostly the same attributes, with some exceptions. Blog posts will have a "blog_name" attribute, while articles do not. Items that have facets and related_urls will return an array of those items, and items that have some multimedia elements (usually photographs) will return an array containing a hash for each multimedia element.
61
4accf6c0 » dwillis
2011-12-13 added README and LICENSE
62 == Future Development
63
64 On the list for future additions is the ability to limit requests to a specific number of hours and to support offsets. Patches, pull requests and feature ideas welcomed.
65
66 == Authors
67
68 Derek Willis, dwillis@nytimes.com
69
70 == Copyright
71
d63bbdb3 » dwillis
2013-05-04 Updated copyright year
72 Copyright (c) 2013 The New York Times Company. See LICENSE for details.
Something went wrong with that request. Please try again.