{"id":13747697,"url":"https://github.com/philnash/bitly","last_synced_at":"2025-05-15T03:07:49.551Z","repository":{"id":485461,"uuid":"111404","full_name":"philnash/bitly","owner":"philnash","description":"🗜 A Ruby wrapper for the bit.ly API","archived":false,"fork":false,"pushed_at":"2025-02-18T10:47:52.000Z","size":471,"stargazers_count":452,"open_issues_count":1,"forks_count":137,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-05-14T11:03:07.329Z","etag":null,"topics":["api-client","api-wrapper","bitly","bitly-api","bitly-v4","shorten-urls","url-shortener"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/bitly","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/philnash.png","metadata":{"files":{"readme":"README.md","changelog":"History.txt","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"philnash"}},"created_at":"2009-01-20T23:40:41.000Z","updated_at":"2025-04-28T12:13:41.000Z","dependencies_parsed_at":"2024-02-11T18:05:52.828Z","dependency_job_id":"46828e7b-edd1-457b-9ab1-d9a5223aa4c8","html_url":"https://github.com/philnash/bitly","commit_stats":{"total_commits":262,"total_committers":31,"mean_commits":8.451612903225806,"dds":0.1564885496183206,"last_synced_commit":"a2ac1751507cdb5fce4f67e17f342bce62ba1732"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philnash%2Fbitly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philnash%2Fbitly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philnash%2Fbitly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philnash%2Fbitly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/philnash","download_url":"https://codeload.github.com/philnash/bitly/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254160589,"owners_count":22024571,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","api-wrapper","bitly","bitly-api","bitly-v4","shorten-urls","url-shortener"],"created_at":"2024-08-03T06:01:38.320Z","updated_at":"2025-05-15T03:07:44.538Z","avatar_url":"https://github.com/philnash.png","language":"Ruby","funding_links":["https://github.com/sponsors/philnash"],"categories":["Ruby"],"sub_categories":[],"readme":"# Bitly\n\nA Ruby gem for using the version 4 [Bitly API](https://dev.bitly.com/) to shorten links, expand short links and view metrics across users, links and organizations.\n\n[![Gem version](https://badge.fury.io/rb/bitly.svg)](https://rubygems.org/gems/bitly) ![Build status](https://github.com/philnash/bitly/workflows/tests/badge.svg) [![Maintainability](https://api.codeclimate.com/v1/badges/f8e078b468c1f2aeca53/maintainability)](https://codeclimate.com/github/philnash/bitly/maintainability) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=philnash_bitly\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=philnash_bitly) [![Inline docs](https://inch-ci.org/github/philnash/bitly.svg?branch=master)](https://inch-ci.org/github/philnash/bitly)\n\n* [Bitly](#bitly)\n  * [Installation](#installation)\n  * [Usage](#usage)\n    * [Authentication](#authentication)\n    * [Creating an API client](#creating-an-api-client)\n    * [Shorten a link](#shorten-a-link)\n    * [Expand a link](#expand-a-link)\n  * [Available API Endpoints](#available-api-endpoints)\n    * [Groups](#groups)\n    * [Organizations](#organizations)\n    * [Users](#users)\n    * [Bitlinks](#bitlinks)\n    * [QR codes](#qr-codes)\n    * [Custom Bitlinks](#custom-bitlinks)\n    * [Campaigns](#campaigns)\n    * [BSDs (Branded Short Domains)](#bsds-branded-short-domains)\n    * [Webhooks](#webhooks)\n  * [Customising HTTP requests](#customising-http-requests)\n    * [Build your own adapter](#build-your-own-adapter)\n  * [Development](#development)\n  * [Contributing](#contributing)\n  * [License](#license)\n  * [Code of Conduct](#code-of-conduct)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'bitly'\n```\n\nAnd then execute:\n\n```bash\n$ bundle install\n```\n\nOr install it yourself as:\n\n```bash\n$ gem install bitly\n```\n\n## Usage\n\nFor a quick introduction, read this blog post on [how to use the Bitly API in Ruby](https://philna.sh/blog/2022/11/09/how-to-use-the-bitly-api-in-ruby/).\n\n### Authentication\n\nAll API endpoints require authentication with an OAuth token. You can get your own OAuth token from the [Bitly console](https://app.bitly.com/). Click on the account drop down menu, then _Profile Settings_ then _Generic Access Token_. Fill in your password and you can generate an OAuth access token.\n\nFor other methods to generate access tokens for users via OAuth flows, see the [Authentication documentation](docs/authentication.md).\n\nOnce you have an access token you can use all the API methods.\n\n### Creating an API client\n\nAll API methods are available through the `Bitly::API::Client`. Initialise the client with the access token like so:\n\n```ruby\nclient = Bitly::API::Client.new(token: token)\n```\n\nYou can then use the client to perform actions with the API\n\n### Shorten a link\n\nWith an authenticated client you can shorten a link like so:\n\n```ruby\nbitlink = client.shorten(long_url: \"http://example.com\")\nbitlink.link\n# =\u003e http://bit.ly/2OUJim0\n```\n\n### Expand a link\n\nWith an authorised you can expand any Bitlink.\n\n```ruby\nbitlink = client.expand(bitlink: \"bit.ly/2OUJim0\")\nbitlink.long_url\n# =\u003e http://example.com\n```\n\n## Available API Endpoints\n\nThis gem supports the following active v4 API endpoints for the[Bitly API](https://dev.bitly.com/api-reference).\n\n### Groups\n\n[Groups documentation](docs/groups.md)\n\n- [x] [Retrieve groups (`GET /v4/groups`)](https://dev.bitly.com/api-reference/#getGroups)\n- [x] [Retrieve group (`GET /v4/groups/{group_guid}`)](https://dev.bitly.com/api-reference/#getGroup)\n- [x] [Update group (`PATCH /v4/groups/{group_guid}`)](https://dev.bitly.com/api-reference/#updateGroup)\n- [x] [Retrieve tags by group (`GET /v4/groups/{group_guid}/tags`)](https://dev.bitly.com/api-reference/#getGroupTags)\n- [x] [Retrieve group preferences (`GET /v4/groups/{group_guid}/preferences`)](https://dev.bitly.com/api-reference/#getGroupPreferences)\n- [x] [Update group preferences (`PATCH /v4/groups/{group_guid}/preferences`)](https://dev.bitly.com/api-reference/#updateGroupPreferences)\n- [x] [Retrieve Bitlinks by group (`GET /v4/groups/{group_guid}/bitlinks`)](https://dev.bitly.com/api-reference/#getBitlinksByGroup)\n- [x] [Retrieve sorted Bitlinks by group (`GET /v4/groups/{group_guid}/bitlinks/{sort}`)](https://dev.bitly.com/api-reference/#getSortedBitlinks)\n- [x] [Retrieve group shorten counts (`GET /v4/groups/{group_guid}/shorten_counts`)](https://dev.bitly.com/api-reference/#getGroupShortenCounts)\n- [x] [Retrieve click metrics for a group by referring networks (`GET /v4/groups/{group_guid}/referring_networks`)](https://dev.bitly.com/api-reference/#GetGroupMetricsByReferringNetworks)\n- [x] [Retrieve click metrics for a group by countries (`GET /v4/groups/{group_guid}/countries`)](https://dev.bitly.com/api-reference/#getGroupMetricsByCountries)\n- [X] [Retrieve QR codes for a group (`GET /v4/groups/{group_guid}/qr-codes`)](https://dev.bitly.com/api-reference/#listQRMinimal)\n- [ ] __[premium]__ [Retrieve click metrics for a group by city (`GET /v4/groups/{group_guid}/cities`)](https://dev.bitly.com/api-reference/#getGroupMetricsByCities)\n- [ ] __[premium]__ [Get group overrides (`GET /v4/groups/{group_guid}/overrides`)](https://dev.bitly.com/api-reference/#getOverridesForGroups)\n\n### Organizations\n\n[Organizations documentation](docs/organizations.md)\n\n- [x] [Retrieve organizations (`GET /v4/organizations`)](https://dev.bitly.com/api-reference/#getOrganizations)\n- [x] [Retrieve organization (`GET /v4/organizations/{organization_guid}`)](https://dev.bitly.com/api-reference/#getOrganization)\n- [x] [Retrieve organization shorten counts (`GET /v4/organizations/{organization_guid}/shorten_counts`)](https://dev.bitly.com/api-reference/#getOrganizationShortenCounts)\n\n### Users\n\n[Users documentation](docs/users.md)\n\n- [x] [Retrieve user (`GET /v4/user`)](https://dev.bitly.com/api-reference/#getUser)\n- [x] [Update user (`PATCH /v4/user`)](https://dev.bitly.com/api-reference/#updateUser)\n\n### Bitlinks\n\n[Bitlinks documentation](docs/bitlinks.md)\n\n- [x] [Shorten a link (`POST /v4/shorten`)](https://dev.bitly.com/api-reference/#createBitlink)\n- [x] [Expand a Bitlink (`POST /v4/expand`)](https://dev.bitly.com/api-reference/#expandBitlink)\n- [x] [Retrieve a Bitlink (`GET /v4/bitlinks/{bitlink}`)](https://dev.bitly.com/api-reference/#getBitlink)\n- [x] [Create a Bitlink (`POST /v4/bitlinks`)](https://dev.bitly.com/api-reference/#createFullBitlink)\n- [x] [Update a Bitlink (`PATCH /v4/bitlinks/{bitlink}`)](https://dev.bitly.com/api-reference/#updateBitlink)\n- [ ] [Delete an unedited hash Bitlink (`DELETE /v4/bitlinks/{bitlink}`)](https://dev.bitly.com/api-reference/#deleteBitlink)\n- [x] [Get clicks for a Bitlink (`GET /v4/bitlinks/{bitlink}/clicks`)](https://dev.bitly.com/api-reference/#getClicksForBitlink)\n- [x] [Get clicks summary for a Bitlink (`GET /v4/bitlinks/{bitlink}/clicks/summary`)](https://dev.bitly.com/api-reference/#getClicksSummaryForBitlink)\n- [x] [Get metrics for a Bitlink by countries (`GET /v4/bitlinks/{bitlink}/countries`)](https://dev.bitly.com/api-reference/#getMetricsForBitlinkByCountries)\n- [x] [Get metrics for a Bitlink by referrers (`GET /v4/bitlinks/{bitlink}/referrers`)](https://dev.bitly.com/api-reference/#getMetricsForBitlinkByReferrers)\n- [x] [Get metrics for a Bitlink by referring domains (`GET /v4/bitlinks/{bitlink}/referring_domains`)](https://dev.bitly.com/api-reference/#getMetricsForBitlinkByReferringDomains)\n- [x] [Get metrics for a Bitlink by referrers by domain (`GET /v4/bitlinks/{bitlink}/referrers_by_domains`)](https://dev.bitly.com/api-reference/#getMetricsForBitlinkByReferrersByDomains)\n- [ ] __[premium]__ [Get metrics for a Bitlink by city (`GET /v4/bitlinks/{bitlink}/cities`)](https://dev.bitly.com/api-reference/#getMetricsForBitlinkByCities)\n- [ ] __[premium]__ [Get metrics for a Bitlink by device type (`GET /v4/bitlinks/{bitlink}/devices`)](https://dev.bitly.com/api-reference/#getMetricsForBitlinkByDevices)\n\n### QR codes\n\n[QR codes documentation](docs/qrcodes.md)\n\n- [x] [Retrieve a QR code (`GET /v4/qr-codes/{qrcode_id}`)](https://dev.bitly.com/api-reference/#getQRCodeByIdPublic)\n- [x] [Retrieve the scans summary for a QR code (`GET /v4/qr-codes/{qrcode_id}/scans/summary`)](https://dev.bitly.com/api-reference/#getScanMetricsSummaryForQRCode)\n- [x] [Retrieve a QR code image (`GET /v4/qr-codes/{qrcode_id}/image`)](https://dev.bitly.com/api-reference/#getQRCodeImagePublic)\n\n### Custom Bitlinks\n\n- [ ] [Add custom Bitlink (`POST /v4/custom_bitlinks`)](https://dev.bitly.com/api-reference/#addCustomBitlink)\n- [ ] __[premium]__ [Retrieve custom Bitlink (`GET /v4/custom_bitlinks/{custom_bitlink}`)](https://dev.bitly.com/api-reference/#getCustomBitlink)\n- [ ] __[premium]__ [Update custom Bitlink (`PATCH /v4/custom_bitlinks/{custom_bitlink}`)](https://dev.bitly.com/api-reference/#updateCustomBitlink)\n- [ ] __[premium]__ [Get metrics for a custom Bitlink by destination (`GET /v4/custom_bitlinks/{custom_bitlink}/clicks_by_destination`)](https://dev.bitly.com/api-reference/#getCustomBitlinkMetricsByDestination)\n- [ ] __[premium]__ [Get clicks for a custom Bitlin's entire history (`GET /v4/custom_bitlinks/{custom_bitlink}/clicks`)](https://dev.bitly.com/api-reference/#getClicksForCustomBitlink)\n\n### Campaigns\n\n- [ ] __[premium]__ [Retrieve campaigns (`GET /v4/campaigns`)](https://dev.bitly.com/api-reference/#getCampaigns)\n- [ ] __[premium]__ [Create campaign (`POST /v4/campaigns`)](https://dev.bitly.com/api-reference/#createCampaign)\n- [ ] __[premium]__ [Retrieve campaign (`GET /v4/campaigns/{campaign_guid}`)](https://dev.bitly.com/api-reference/#getCampaign)\n- [ ] __[premium]__ [Update campaign (`PATCH /v4/campaigns/{campaign_guid}`)](https://dev.bitly.com/api-reference/#updateCampaign)\n- [ ] __[premium]__ [Retrieve channels (`GET /v4/channels`)](https://dev.bitly.com/api-reference/#getChannels)\n- [ ] __[premium]__ [Create channel (`POST /v4/channels`)](https://dev.bitly.com/api-reference/#createChannel)\n- [ ] __[premium]__ [Retrieve channel (`GET /v4/channels/{channel_guid}`)](https://dev.bitly.com/api-reference/#getChannel)\n- [ ] __[premium]__ [Update channel (`PATCH /v4/channels/{channel_guid}`)](https://dev.bitly.com/api-reference/#updateChannel)\n\n### BSDs (Branded Short Domains)\n\n[Branded Short Domains documentation](docs/branded_short_domains.md)\n\n- [x] [Retrieve BSDs (`GET /v4/bsds`)](https://dev.bitly.com/api-reference/#getBSDs)\n\n### Webhooks\n\n- [ ] __[premium]__ [Get webhooks (`GET /v4/organizations/{organization_guid}/webhooks`)](https://dev.bitly.com/api-reference/#getWebhooks)\n- [ ] __[premium]__ [Create a webhook (`POST /v4/webhooks`)](https://dev.bitly.com/api-reference/#createWebhook)\n- [ ] __[premium]__ [Retrieve a webhook (`GET /v4/webhooks/{webhook_guid}`)](https://dev.bitly.com/api-reference/#getWebhook)\n- [ ] __[premium]__ [Update a webhook (`POST /v4/webhooks/{webhook_guid`)](https://dev.bitly.com/api-reference/#updateWebhook)\n- [ ] __[premium]__ [Delete a webhook (`DELETE /v4/webhooks/{webhook_guid}`)](https://dev.bitly.com/api-reference/#deleteWebhook)\n- [ ] __[premium]__ [Verify a webhook (`POST /v4/webhooks/{webhook_guid}/verify`)](https://dev.bitly.com/api-reference/#verifyWebhook)\n\n## Customising HTTP requests\n\nThis gem comes with an HTTP client that can use different adapters. It ships with a `Net::HTTP` adapter that it uses by default.\n\nIf you want to control the connection, you can create your own instance of the `Net::HTTP` adapter and pass it options for an HTTP proxy or options that control the request. For example, to control the `read_timeout` you can do this:\n\n```ruby\nadapter = Bitly::HTTP::Adapters::NetHTTP.new(request_options: { read_timeout: 1 })\nhttp_client = Bitly::HTTP::Client.new(adapter)\napi_client = Bitly::API::Client.new(http: http_client, token: token)\n```\n\nSimilarly, you can use an HTTP proxy with the adapter by passing the proxy variables to the adapter's constructor.\n\n```ruby\nadapter = Bitly::HTTP::Adapters::NetHTTP.new(proxy_addr: \"example.com\", proxy_port: 80, proxy_user: \"username\", proxy_pass: \"password\")\nhttp_client = Bitly::HTTP::Client.new(adapter)\napi_client = Bitly::API::Client.new(http: http_client, token: token)\n```\n\n### Build your own adapter\n\nIf you want even more control over the request, you can build your own adapter. An HTTP adapter within this gem must have a `request` instance method that receives a `Bitly::HTTP::Request` object and returns an array of four objects:\n\n1. The response status code\n2. The body of the response as a string\n3. The response headers as a hash\n4. A boolean denoting whether the response was a success or not\n\nSee `./src/bitly/http/adapters/net_http.rb` for an example.\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/philnash/bitly. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the Bitly project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/philnash/bitly/blob/master/CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilnash%2Fbitly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilnash%2Fbitly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilnash%2Fbitly/lists"}