Add this line to your application's Gemfile:
gem 'guidestar'
Or install it yourself as:
$ gem install guidestar
Then configure it with an initializer like /config/initializers/guidestar.rb:
Guidestar.configure do |config|
config.username = '[email protected]'
config.password = 'l3tm31n'
end
Once you initialize it, you can use it in your code via:
results = Guidestar.search(:keyword => 'monkeys', :limit => 20)
Or you can create a Guidestar::Client object and go from there:
client = Guidestar::Client.new
results = client.search(:keyword => 'monkeys', :limit => 20)
# OR
results = client.keyword('monkeys').per(20).search
# or any combination of the above methods
There are four main API methods that you can use:
Guidestar.search # tested
Guidestar.detailed_search # tested
Guidestar.charity_check # untested
Guidestar.npo_validation # untested
See https://gsservices.guidestar.org/GuideStar_SearchService/WebServiceSearchQuery.xsd for detailed search parameters.
The Guidestar::Result object behaves like an array, but includes some extra fields for your usage:
results.xml
# => raw xml data
results.search_time
# => 0.12
results.total_count
# => 1292
results.total_pages
# => 52
You can iterate through the results like any Enumerable:
results.each do |org|
org.name
# => 'Monkey Paradise'
org.ein
# => '23-5553434'
org.ein.to_i # with some magic
# => 235553434
org.tax_deductible?
# true
end
For getting the next page of results, it behaves similarly to kaminari or will_paginate:
results.page(2).each { |more_orgs| puts more_orgs.name }
If you should ever need direct access to the array of results, just hit:
results.organizations
Ruby APIs should be super flexible in usage, so this gem lets you access the data how you want. Pass in your options all at once or chain them. Create a new search or use the result to paginate or adjust the search as needed.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Added some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request