Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 189 lines (110 sloc) 5.872 kb
9073d08 @jtadeulopes Add link to travis-ci.
jtadeulopes authored
1 = googl
3dc078f @jtadeulopes Added readme.
jtadeulopes authored
2
3 Google URL Shortener API in Ruby
4
9073d08 @jtadeulopes Add link to travis-ci.
jtadeulopes authored
5 == Continuous Integration
6
d04d200 @jtadeulopes Changed Travis status image url.
jtadeulopes authored
7 {<img src="https://secure.travis-ci.org/zigotto/googl.png" />}[http://travis-ci.org/zigotto/googl]
9073d08 @jtadeulopes Add link to travis-ci.
jtadeulopes authored
8
3dc078f @jtadeulopes Added readme.
jtadeulopes authored
9 == Basic Usage
10
11 === Shorten a long URL
12
d094cbf @jtadeulopes Update readme.
jtadeulopes authored
13 url = Googl.shorten('http://www.zigotto.com')
3dc078f @jtadeulopes Added readme.
jtadeulopes authored
14
15 url.short_url
16 => "http://goo.gl/ump4S"
17
18 url.long_url
19 => "http://www.zigotto.com/"
20
b3b7165 @jtadeulopes Update readme.
jtadeulopes authored
21 url.qr_code
22 => "http://goo.gl/ump4S.qr"
23
36c4719 @jtadeulopes Updated Readme and doc.
jtadeulopes authored
24 url.info
25 => "http://goo.gl/ump4S.info"
26
3dc078f @jtadeulopes Added readme.
jtadeulopes authored
27 === Expand a short URL
28
d094cbf @jtadeulopes Update readme.
jtadeulopes authored
29 url = Googl.expand('http://goo.gl/ump4S')
3dc078f @jtadeulopes Added readme.
jtadeulopes authored
30
31 url.long_url
32 => "http://www.zigotto.com/"
5d8c1fe @jtadeulopes Update readme.
jtadeulopes authored
33
b3b7165 @jtadeulopes Update readme.
jtadeulopes authored
34 == Authentication
35
36 The Google URL Shortener API supports the OAuth and ClientLogin mechanisms for authenticating.
37
38 For shorten requests, each short URL for an authenticated user is unique, and thus will gather unique click statistics. In addition, it shows up on the user's dashboard at http://goo.gl.
39
40 === ClientLogin
41
42 client = Googl.client('user@gmail.com', 'my_valid_password')
43
44 url = client.shorten('https://github.com/zigotto/googl')
45 url.short_url
46 => http://goo.gl/DWDfi
47
48 Go to http://goo.gl to see URL statistics.
49
50 === OAuth
51
49c66ff @jtadeulopes Update read with oauth docs.
jtadeulopes authored
52 Google supports three flows of OAuth 2.0
53
54 * The <b>client-side</b> flow for JavaScript applications running in a browser. (TODO)
55 * The <b>server-side</b> flow for web applications with servers that can securely store persistent information.
56 * The <b>native application</b> flow for desktop and mobile applications.
57
58 Today, gem googl support only <b>server-side</b> and <b>native application</b>.
59
60 ==== Server-side web applications
61
62 You'll need to register your application with Google to get a <em>client_id</em> and record the <em>redirect_uri</em> you'd like to use.
63 See the Registering[http://code.google.com/apis/accounts/docs/OAuth2.html#Registering] your app with Google section for details on how to register.
64
65 client = Googl::OAuth2.server("client_id", "client_secret", "redirect_uri")
66
67 Redirect your users to
68
69 client.authorize_url
70
71 After the user approves access or chooses not to, we'll redirect to the <em>redirect_uri</em> you passed us and append either an authorization code.
72
73 client.request_access_token(params["code"])
74 client.authorized?
75 => true
76
77 Now you can get a user's history, shorten url, etc...
78
79 history = client.history
80 history.total_items
81 => 19
82
83 url = Googl.shorten('https://github.com/zigotto/googl')
84 url.short_url
85 => http://goo.gl/DWDfi
86
87 ==== Native applications
88
89 You'll need to register your application with Google to get a <em>client_id</em> and record the special <em>redirect_uri: urn:ietf:wg:oauth:2.0:oob</em>.
90 See the Registering[http://code.google.com/apis/accounts/docs/OAuth2.html#Registering] your app with Google section for details on how to register.
91
92 When you use this redirect_uri, instead of redirecting the user's browser to a page on your site with an authorization code, Google will display the authorization code or error response in the title of the page and a text field with instructions for the user to copy and paste it in to your application. Your application can either monitor the window title of a web-view or browser window it launches and close it once the authorization code appears or prompt the user to copy and paste the code.
93
94 client = Googl::OAuth2.native("client_id", "client_secret")
95
96 Open a browser or a webview to the OAuth dialog at
97
98 client.authorize_url
99
100 In the native app flow, after the user approves access, we'll display the authorization code in the title of the page and in a text input with instructions for the user to copy and paste the code to your application
101
102 code = "copied code"
103 client.request_access_token(code)
104 client.authorized?
105 => true
b3b7165 @jtadeulopes Update readme.
jtadeulopes authored
106
fa168ec @jtadeulopes Added documentation and update README with info of analytics.
jtadeulopes authored
107 == Analytics
108
109 Expands a short URL or gets creation time and analytics
110
111 For analytics and additional information to return (using the :projection parameter)
112
113 :full returns the creation timestamp and all available analytics
114 :analytics_clicks returns only click counts
115 :analytics_top_strings returns only top string counts (e.g. referrers, countries, etc)
116
117 === Get Analytics
118
119 url = Googl.expand('http://goo.gl/DWDfi', :projection => :full)
120
121 url.analytics.all_time.browsers.first.label
122 => "Chrome"
123 url.analytics.all_time.browsers.first.count
124 => "11"
125
126 A summary of the click analytics for the short and long URL
127
128 url.analytics
129
130 Analytics details for a particular window of time; counts in this object are of clicks that occurred within the most recent window of this length.
131
132 url.analytics.all_time
133 url.analytics.month
134 url.analytics.week
135 url.analytics.day
136 url.analytics.two_hours
137
138 Number of clicks on this short URL. Replace (*) for all_time, month, week, day or two_hours
139
140 url.analytics.*.short_url_clicks
141
142 Number of clicks on all goo.gl short URLs pointing to this long URL.
143
144 url.analytics.*.long_url_clicks
145
146 Top referring hosts, e.g. "www.google.com"; sorted by (descending) click counts. Only present if this data is available.
147
148 url.analytics.*.referrers
149
150 Top countries (expressed as country codes), e.g. "US" or "DE"; sorted by (descending) click counts.
151
152 url.analytics.*.countries
153
154 Top browsers, e.g. "Chrome"; sorted by (descending) click counts.
155
156 url.analytics.*.browsers
157
158 Top platforms or OSes, e.g. "Windows"; sorted by (descending) click counts.
159
160 url.analytics.*.platforms
161
162 For details, see http://code.google.com/intl/pt-BR/apis/urlshortener/v1/reference.html#resource_url
163
36c4719 @jtadeulopes Updated Readme and doc.
jtadeulopes authored
164 == History
165
166 Gets a user's history of shortened URLs. (Authenticated)
167
168 client = Googl.client('user@gmail.com', 'my_valid_password')
169
170 history = client.history
171 history.total_items
172 => 19
173
174 A list of URL.
175
176 history.items
177
178 Analytics details for all items
179
180 history = client.history(:projection => :analytics_clicks)
181
5d8c1fe @jtadeulopes Update readme.
jtadeulopes authored
182 == Installation
183
184 gem install googl
185
186 == License
187
03bad51 @jtadeulopes Adjust readme.
jtadeulopes authored
188 MIT License. Copyright 2011 Zigotto®. http://www.zigotto.com.br
Something went wrong with that request. Please try again.