google_url_shortener

h1. Google Url Shortener.

• Overview
• Installation
• Usage
• CLI
• Specs
• Bugs

h2. Overview

Google URL Shortener is a library to interact with the goo.gl URL shortener API. It provides:

• A CLI to easily shorten/expand URL's
• A clean API to handle shortening/expanding URL's in an application
• An interface to view analytical data for any short URL

h2. Installation

The project is hosted on rubygems.org. Getting it is simple:

pre. gem install google_url_shortener

h2. Usage

h3. Setup

You need to provide an API key (get one "here":https://code.google.com/apis/console) to use the URL shortener service. To do this set the @api_key@:

pre. Google::UrlShortener::Base.api_key = "KEY"

You can also turn on verbose logging to inspect requests made by the library. Behind the scenes the library uses "RestClient":https://github.com/archiloque/rest-client to call the API, therefore whatever you set here will be used as the RestClient log (@RestClient.log@).

pre. Google::UrlShortener::Base.log = $stdout

h3. Shorten/Expand a URL

To shorten a URL:

pre. url = Google::UrlShortener::Url.new(:long_url => "http://blog.josh-nesbitt.net") url.shorten! # => http://goo.gl/r5akx

Or the shorthand form:

pre. Google::UrlShortener.shorten!("http://blog.josh-nesbitt.net") # => http://goo.gl/r5akx

To expand a URL:

pre. url = Google::UrlShortener::Url.new(:short_url => "http://goo.gl/r5akx") url.expand! # => http://blog.josh-nesbitt.net

Or the shorthand form:

pre. Google::UrlShortener.expand!("http://goo.gl/r5akx") # => http://blog.josh-nesbitt.net

h3. Getting more data from an expanded URL

More data is available from a URL once it's been expanded:

pre. url = Google::UrlShortener::Url.new(:short_url => "http://goo.gl/r5akx") url.expand! # => http://blog.josh-nesbitt.net url.created_at # => 2011-01-11 url.created_at.year # => 2011 url.analytics # => Google::UrlShortener::Analytics url.analytics.all # => Google::UrlShortener::AnalyticsGroup url.analytics.all.browsers # => { "Chrome" => 1 } url.analytics.all.countries # => { "GB" => 1 } url.analytics.all.platforms # => { "Macintosh" => 1 } url.analytics.all.referrers # => { "Unknown/empty" => 1 } url.analytics.all.long_url_clicks # => 23 url.analytics.all.short_url_clicks # => 3

Available scopes are:

pre. all month week day two_hours

E.g: @url.analytics.month@.

h2. CLI

h3. Basic usage

There is also a CLI wrapper for Google URL Shortener. Firstly, you need to tell the CLI your API key (get one "here":https://code.google.com/apis/console):

pre. googl install AIzaSyByl4x5CMcnm2rNWafmaUz5sljmzMWIgZ0

This saves your API key in @~/.googl@.

To shorten a URL:

pre. googl shorten http://example.com googl s http://example.com

To expand a URL:

pre. googl expand http://goo.gl/1234 googl e http://goo.gl/1234

You can also get analytical data from a short URL using the @-a@ or @--analytics@ flag:

pre. googl expand http://goo.gl/1234 -a

h3. Tips

You can use the CLI alongside something like @pbcopy@ to make shortening URL's crazy fast:

pre. googl shorten http://example.com | pbcopy

Also use a bash function to simplify it further:

pre. shorten (){ googl shorten $1 | pbcopy echo "$1 shortened and copied to clipboard" }

Which can be used as:

pre. shorten http://example.com

h2. Specs

Run the specs with the following command:

pre. bundle exec rspec --require ./spec/spec_helper.rb --format nested --color spec/lib/.rb spec/lib/**/.rb

h2. Bugs

If you have any problems with Google Url Shortener, please file an "issue":http://github.com/joshnesbitt/google_url_shortener/issues.

h2. Note on Patches/Pull Requests

• Fork the project.
• Make your feature addition or bug fix.
• Add tests for it. This is important so I don't break it in a future version unintentionally.
• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
• Send me a pull request. Bonus points for topic branches.

h2. Copyright

Copyright (c) 2010 Josh Nesbitt [e-mail]. See LICENSE for details.