Skip to content
Ruby wrapper for The City API
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

The City Ruby Gem

Gem Version Dependency Status Build Status Coverage Status

A Ruby interface to the The City API. For more information about The City platform, see


gem install thecity


The City API requires you to authenticate via OAuth, so you'll need to register your application with The City under the Admin | API panel.

Your new application will be assigned a key/secret pair (app_id/app_secret). You'll need to configure these values before you make a request or else you'll get the error:

Bad Authentication data

You can pass configuration options as a block to

client = do |config|
  config.app_id        = "YOUR_APP_ID"
  config.app_secret    = "YOUR_APP_SECRET"
  config.access_token  = "OAUTH_ACCESS_TOKEN"


client =
client.app_id        = "YOUR_APP_ID"
client.app_secret    = "YOUR_APP_SECRET"
client.access_token  = "OAUTH_ACCESS_TOKEN"

Alternately, you can set the following environment variables:


Usage Examples

All examples require an authenticated TheCity client with a valid access_token. See the section on configuration.

After configuration, requests can be made like so:

Get the authenticated user (current user)

Post a topic

client.post_topic(:group_id => 1234567, :title => 'Mr. Watson, come here', :body => 'I want to see you.')

Fetch the groups the current user belongs to


For more usage examples, please see the full documentation.



You should follow @thecity and @thecity_status on Twitter for announcements and updates about this library.

The City Builder API Developer Group

For more in depth discussiong regarding The City app platform and APIs, please join the 'API' group on Builders.

Apps Wiki

Does your church or organization use this gem? Add it to the apps wiki!

Advanced Configuration


The Faraday middleware stack is fully configurable and is exposed as a Faraday::Builder object. You can modify the default middleware in-place:

client.middleware.insert_after TheCity::Response::RaiseError, CustomMiddleware

A custom adapter may be set as part of a custom middleware stack:

client.middleware =
  & do |builder|
    # Specify a middleware stack here
    builder.adapter :some_other_adapter

Contributing to thecity gem

Submitting an Issue

We use the GitHub issue tracker to track bugs and features. Before submitting a bug report or feature request, check to make sure it hasn't already been submitted. When submitting a bug report, please include a Gist that includes a stack trace and any details that may be necessary to reproduce the bug, including your gem version, Ruby version, and operating system. Ideally, a bug report should include a pull request with failing specs.

Submitting a Pull Request

  1. Fork the repository.
  2. Create a topic branch.
  3. Preferably, add specs for your unimplemented feature or bug fix.
  4. Run bundle exec rake spec. If your specs pass, return to step 3.
  5. Implement your feature or bug fix.
  6. Run bundle exec rake spec. If your specs fail, return to step 5.
  7. Add documentation for your feature or bug fix.
  8. Run bundle exec rake yard.
  9. Commit and push your changes.
  10. Submit a pull request.


Copyright (c) 2013 Robert Leib. See LICENSE for details.

You can’t perform that action at this time.