thoughtbot / clearbit Goto Github PK

View Code? Open in Web Editor NEW

30.0 9.0 11.0 54 KB

Go client library and command line interface to the Clearbit API

License: MIT License

Shell 3.70% Go 96.30%

clearbit's Introduction

clearbit

clearbit is a client library and command-line interface for the Clearbit API.

Install for the command line

For OS X users, you can install and upgrade through the Homebrew package:

brew tap thoughtbot/formulae
brew update
brew install clearbit

Or, for anyone with Go installed, you can install from the command-line:

go get -u github.com/thoughtbot/clearbit/cmd/clearbit

Then, store your Clearbit API key in ~/.clearbit_key.

Usage from the command line

Use the subcommands to interact with the different Clearbit API endpoints.

Get detailed information about a person from their email address:

$ clearbit enrich [email protected]

Get data about a company from its domain:

$ clearbit enrich thoughtbot.com

Get contact details for a company (role & seniority picklist):

$ clearbit prospect -role marketing -seniority executive thoughtbot.com

Since each command produces JSON as its output, the clearbit command pairs nicely with jq for processing.

Get company copy-pasteable company contacts:

$ clearbit prospect thoughtbot.com |
    jq '.[] | "\(.name.fullName) <\(.email)>"'

Run clearbit help [subcommand] for details on additional options.

Usage from Go

The clearbit package exposes types for interacting with the Clearbit API and the data it returns.

import "github.com/thoughtbot/clearbit"

client, _ := clearbit.NewClient(os.Getenv("CLEARBIT_API_KEY"))

bernerd, _ := client.EnrichPerson("[email protected]")
thoughtbot, _ := client.EnrichCompany(bernerd.Employment.Domain)

prospects, _ := client.Prospect(clearbit.ProspectQuery{
  Domain: "thoughtbot.com",
  Titles: []string{"CEO", "CTO", "VP"},
})

for _, prospect := range prospects {
  prospectDetails, _ := client.EnrichPerson(prospect.Email)
}

For detailed API documentation, read the go docs.

Contributing

We love pull requests from everyone. By participating in this project, you agree to abide by the thoughtbot code of conduct.

We expect everyone to follow the code of conduct anywhere in thoughtbot's project codebases, issue trackers, chatrooms, and mailing lists.

License

About

clearbit is maintained by Bernerd Schaefer and thoughtbot's Go development team.

The names and logos for thoughtbot are trademarks of thoughtbot, inc.

We love open source software! See our other projects or hire us to help build your product.

clearbit's People

Contributors

Stargazers

Watchers

Forkers

bernerdschaefer siadat srt32 fabianoleittes cp mtvillwock joejose2728 kundeshi eudols sushraju isabella232

clearbit's Issues

Support comma-separated titles in prospect command

It would be nice to be able to search titles when prospecting with:

$ clearbit prospect -title CEO,COO company.com

In addition to

$ clearbit prospect -title CEO -title COO company.com

Requested by @croaky in #15 (comment).

Proposal: Clearbit client API

I'd like to start building out a proper Client for communicating with the Clearbit API.

With that in mind, here's an example program using a proposed API for the client package:

package main

func main() {
    client, _ := clearbit.NewClient(os.Getenv("CLEARBIT_API_KEY"))

    bernerd, _ := client.EnrichPerson(clearbit.PersonQuery{
        Email: "[email protected]",
    })

    dan, thoughtbot, _ := client.EnrichPersonCombined(clearbit.PersonQuery{
        Email:     "[email protected]",
        WebhookID: "abc1234",
        Subscribe: true,
    })

    potentialContacts, _ := client.Prospect(clearbit.ProspectQuery{
        Domain: "thoughtbot.com",
        Titles: []string{"CEO", "CTO", "VP"},
    })

    for _, contact := range potentialContacts {
        contactDetails, _ := client.EnrichPerson(contact)

        fmt.Println(contactDetails.Name.FullName)
        fmt.Println(contactDetails.Employment.Title)
        fmt.Println(contactDetails.Twitter.Handle)
    }
}

And here's the godocs for the proposed API, generated from https://gist.github.com/bernerdschaefer/858567592a7e50048629:

type Client struct{}

func NewClient(apiKey string) (*Client, error)

func (*Client) EnrichCompany(CompanyQuery) (*Company, error)
    EnrichCompany finds a company by its domain name and returns detailed
    information about it.

func (*Client) EnrichPerson(PersonQuery) (*Person, error)
    EnrichPerson finds a person by their email address and returns detailed
    information about them.

func (*Client) EnrichPersonCombined(PersonQuery) (*Person, *Company, error)
    EnrichPersonCombined finds a person by their email address and returns
    detailed information about them and their company.

func (*Client) Prospect(ProspectQuery) ([]Person, error)
    Prospect finds a company by its domain name and returns basic
    information about the people working there.

type CompanyQuery struct {
    // Company's domain name to look up (required).
    Domain string

    // Setting a webhook_id allows you to get a callback
    // when a company's information is not immediately available.
    // You can also subscribe to changes.
    //
    // If no WebhookID is provided, the client will use Clearbit's
    // streaming API.
    WebhookID string
}

type PersonQuery struct {
    // Email address to look up (required).
    Email string

    // Setting a webhook_id allows you to get a callback
    // when a person's information is not immediately available.
    // You can also subscribe to changes.
    //
    // If no WebhookID is provided, the client will use Clearbit's
    // streaming API.
    WebhookID string

    // Set to true to subscribe to changes.
    Subscribe bool
}

type ProspectQuery struct {
    // Company's domain name to look up (required).
    Domain string

    // Filters results by first or last name (case-insensitive).
    Name string

    // Filters results by one or more titles.
    Titles []string

    // Set to true to exclude email addresses from the results.
    ExcludeEmails bool
}

Open Source

The project is already laced up, so it has a basic CONTRIBUTING.md, LICENSE, and links to our code of conduct.

Should we, then, open source the project:

now, or
after the CLI has stabilized more?

Add Role/Seniority for prospecting

We just added ability to search by Role/Seniority:
http://support.clearbit.com/article/120-employment-role-and-seniority

This would make searches like:

clearbit prospect -seniority executive thoughtbot.com 
# => CEO, CTO, all execs

clearbit prospect -role engineering thoughtbot.com 
# => Hacker, Developer, CTO, etc

clearbit prospect -role engineering -seniority executive thoughtbot.com 
# => VP Engineering, CTO, Chief Technology Officer

Document Homebrew packaging instructions

Clearbit Discovery API

The tentatively proposed interface for the Clearbit Discovery API (#2) is:

clearbit discover --tech marketo --sort alexa_asc

The actual query API is quite rich, supporting many fields, and and or queries, etc. It seems like a nice approach would be to support a few important fields as flags (--tech above), and then allow users to write more complex queries directly if needed.

Looking through Clearbit's supported discovery fields, the most likely to warrant flags look to be:

employees
location
raised
tech

Desired CLI API

Based on API sections:

clearbit prospect
clearbit enrich example.com (#1)
clearbit enrich [email protected] (#1)
clearbit enrich [email protected] --combined
clearbit discover --tech marketo --sort alexa_asc
document available commands in README

`go get` issues

~ % go get github.com/thoughtbot/clearbit/cmd/clearbit
# github.com/thoughtbot/clearbit/cmd/clearbit
src/github.com/thoughtbot/clearbit/cmd/clearbit/enrich.go:16: unknown cli.Command field 'ArgsUsage' in struct literal
src/github.com/thoughtbot/clearbit/cmd/clearbit/main.go:22: unknown cli.StringFlag field 'Destination' in struct literal
src/github.com/thoughtbot/clearbit/cmd/clearbit/prospect.go:16: unknown cli.Command field 'ArgsUsage' in struct literal

Different machine than I was using yesterday, where it worked fine.