RemoteOK API Ruby Client

A ruby client to interact with the RemoteOK API.

Installation

Requirements

• Ruby >= 2.6.0

Add this line to your application's Gemfile:

gem 'remoteok'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install remoteok

Usage

Authentication

RemoteOK does not currently require direct authentication, rather simply exists as a JSON document at the url:

https://remoteok.io/api

Delayed Items & Legal

Items in the API are available 24 hours later than on the web. It is important to note that this document contains it's own legal terms within it, which at the time of writing are:

API Terms of Service: Please link back to the URL on Remote OK and mention Remote OK as a source, so we get traffic back from your site. If you do not we'll have to suspend API access.

Please don't use the Remote OK logo without written permission as they're registered trademarks, please DO use our name Remote OK though

The API feed at /api is delayed by 24 hours so that Google knows it's Remote OK first posting the job to avoid duplicate content problems, if you'd like to advertise or pay for instant API access for all remote jobs (minimum budget $10k/mo), contact @remoteok on Twitter."

You can fetch a realtime version of this document by using

  RemoteOK::Client.new.legal # => String of legal copy.

Getting Started

The gem works through a client object which needs instantiation, and call methods exist on this client.

  client = RemoteOK::Client.new

---

Client Config

The client has a number of configurable options set during instantiation. Multiple options may be provided.

user_agent

The gem will send it's own default user agent but you can override it for your own app.

  client = RemoteOK::Client.new(user_agent: 'hello-there')

debug

Turning on the debug flag will pass a request to HTTParty to print verbose debug output to the console, so that you can inspect whats happening on the network under the hood.

  client = RemoteOK::Client.new(debug: true)

Client Methods

.jobs

Items are returned as an array of RemoteOK::Job objects.

Important: These items are cached in the client once fetched to avoid excessive calls to the live site, make sure to use the #with_fetch method to force a refresh.

  client.jobs # => [Job, Job, Job]

Tag Searching

You can specify specific tags that you'd like the RemoteOK API to search by through tag arguments to the .jobs method.

  client.jobs :ruby, :digital_nomad

This will return all jobs that match on Ruby OR Digital Nomad.

.with_fetch

A chainable method to force the client to fetch items from the live site rather than using the cached information.

  client.with_fetch.jobs # => [Job, Job, Job]

---

Job methods

Jobs are retrieved from the jobs array.

  job = client.jobs.first

.raw

Type: JSON

Returns the raw JSON data associated with the job directly from the API.

  job.raw # => {...}

.slug

Type: String

Returns the job url slug.

  job.slug # => "i-am-a-job-slug"

.id

Type: Integer

Returns the job id.

  job.id # => 123456

.epoch

Type: Integer

Returns the posting epoch as an integer.

  job.epoch # => 1_619_724_426

.date

Type: DateTime

Returns the creation date of the job as a DateTime object.

  job.date # => DateTime<...>

.company

Type: String

Returns the name of the company the job is for.

  job.company # => "Awesome Company"

.company_logo

Type: String

Returns RemoteOK URL for the company logo.

  job.company_logo # => "https://remoteOK.io/assets/jobs/something.png"

.position

Type: String

Returns name of the position (job title)

  job.position # => "Chief Awesome Officer"

.tags

Type: Array

Returns all the tags associated for the job as symbols. These can also be used for searching and filtering the API.

  job.tags # => [:dev, :dot_net, :digital_nomad]

.logo

Type: String

String URL of logo associated with the job.

  job.logo # => "https://remoteOK.io/assets/jobs/jobjob.png"

.description

Type: String

A string containing the job description, directly as it's stored in Remote OK. Be aware that this will likely contain HTML code in the content.

  job.description # => "<p><strong>Our Company</strong>...."

.description_text

Type: String

A best-attempt to extract the raw text from the above, removing HTML tags and formatting.

  job.description_text # => "Our Company...."

.location

Type: String

Written global location for the job.

  job.location # => "North America"

.original

Type: Boolean

Flag for whether it's an original job post

  job.original # => true

.url

Type: String

String URL to the job post on RemoteOK itself

  job.url # => "https://remoteOK.io/remote-jobs/somejob"

.apply_url

Type: String

String URL for candidates to apply to the job

  job.apply_url # => "https://remoteOK.io/remote-jobs/l/somejob"

---

Development

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 the created tag, and push the .gem file to rubygems.org.

---

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/RemoteCTO/remoteok. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

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

Code of Conduct

Everyone interacting in the Remoteok project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.