The VolunteerMatch Public-Use API Gem

VolunteerMatch is a lightweight Ruby wrapper that queries VolunteerMatch's Public-Use API for searching information on nonprofit organizations and active volunteering opportunities.

This gem is inspired by the Ruby API example provided in the vm-contrib repo. Queries are configured based on the attributes applied and return a collection of JSON results.

The Official documentation on using the API can be found at VolunteerMatch.org.

To use VolunteerMatch's Public-Use API, you need to be validated for full access. Complete an online application here in order to get approved for a unique Public-Use key. Until then, you are only able to test helloWorld calls.

Add this line to your application's Gemfile:

gem 'volunteermatch'

And then execute:

$ bundle

Or install it yourself as:

$ gem install volunteermatch

Concealing your API username and key is important. I recommend using dotenv to do so.

client = Volunteermatch::Client.new('username', 'key')

After setting a client, you are able to access all methods below.

Test API Connectivity

vm = client.test("John")
vm.result                   #=> "Hello John!"

Get API Key Status

client.key_status

Search Opportunities (location required)

client.search_opportunities(location: "New York", orgNames: ["red cross"], fieldsToDisplay: ["title", "description"])

Search Organizations (location required)

client.search_organizations(location: "San Francisco", categoryIds: [23], fieldsToDisplay: ["name", "mission"])

Get Metadata (defaults to current version)

client.metadata

Get Service Status

client.service_status

All data obtained through this gem belongs to VolunteerMatch. Please review the Public-Use API Access Agreement for all terms, limitations and restrictions.

After 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.

To 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.

Suggestions, bug reports and pull requests are encouraged for those who would like to take part in improving this gem. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant.

Copyright (c) 2017, Evan Ng

The VolunteerMatch gem is available as open source under the terms of the MIT license.