Fathom API

🛠 An easy to use client with the Fathom API

You'll need a usefathom.com account to use the API, if you don't have one click here to sign up.

As of August 17th, 2021 the API was still early-access, so some endpoints may be different than in production. Feel free to submit a PR or issue. Contributions are welcome!

Installation

Add fathom_api to your application's Gemfile:

bundle add fathom_api
# OR in the Gemfile
gem "fathom_api"

Usage

Create a client to get started, passing an api_key you generate in your Fathom API settings.

client=Fathom::Client.new(api_key: ENV['FATHOM_API_KEY'])

Fetch account details

# Get account detailsclient.account.info# => Fathom::Account

Responses are wrapped in an object that dynamically allows you to call the attributes as if they are an OpenStruct... IE

response=client.account.info# => #<Fathom::Account:0x00007fee844068c8 @attributes=#<OpenStruct id=12345, name="Your account name", email="you@starfleet.org", object="account">>response.name# => "Your account name"response.email# => "you@starfleet.org"

Pagination

When an API's response comes back with a object of "list", we automatically wrap that to attempt to provide some helper methods to ease your implementations.

list=client.sites.list(limit: 1)# => Fathom::List# We provide two helper methods to allow you to get the first or last id from the data responselist.first_idlist.last_id# check if the list has more after it withlist.has_more?# => true# use the next page cursor in your next responselist2=client.sites.list(limit: 1,starting_after: list.last_id)

Sites

client.sites.list# Optionally, pass params in to filter / limit responses# Limit can be between 1 and 100client.sites.list(limit: 1,starting_after: "SITE_ID")# => Fathom::Listclient.sites.retrieve(site_id: site_id)client.sites.create({})# Include `name` and other paramsclient.sites.update(site_id: site_id,{})# Params being updatedclient.sites.delete(site_id: site_id)client.sites.wipe(site_id: site_id)# All return# => Fathom::Site

Events

client.events.list(site_id: site_id)# => Fathom::List# Optionally, pass params in to filter / limit responses# Limit can be between 1 and 100client.events.list(site_id: site_id,limit: 10,starting_after: "EVENT_ID")# => Fathom::Listclient.events.retrieve(site_id: site_id,event_id: event_id)client.events.create(site_id: site_id,{})# Attributes for eventclient.events.update(site_id: site_id,{})# Attributes being updatedclient.events.delete(site_id: site_id,event_id: event_id)client.events.wipe(site_id: site_id,event_id: event_id)# All return# Fathom::Event

Current Visitors

client.current_visitors(site_id: site_id,{})# Can add detailed: true for a more detailed report

Aggregation

client.aggregations.list(entity_id: entity_id,entity_type: entity_type,aggregates: aggregates, **params)

🙏 Contributing

This project uses Standard for formatting Ruby code. Please make sure to run standardrb before submitting pull requests. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Code of Conduct

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

📝 License

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