Skip to content

Latest commit

 

History

History
372 lines (264 loc) · 9.34 KB

README.md

File metadata and controls

372 lines (264 loc) · 9.34 KB
Raw

fullcontact Build Status

fullcontact is a Node.js module that wraps the fullcontact API. It implements the following API endpoints:

If you want any special endpoints or queries on endpoints implemented feel free to make a PR or an issue!

Installation

The module is distributed through npm (node package manager) and can be installed using:

npm install fullcontact --save

The --save automatically adds the module to your package.json definition.

Usage

We are all hackers in our heart that's why this module is build with extensibility and hackibility in mind, there aren't any hidden components and all the API endpoints are implemented as separate constructors so they can be improved and hacked when needed.

You require the module as any other node.js module:

var FullContact = require('fullcontact');

//
// The constructors are directly exposed on the FullContact constructor:
//
FullContact.Location;
FullContact.Person;
FullContact.Email;
FullContact.Name;
FullContact.Company;

To create a new client you simply need to construct the module with your FullContact API key:

var FullContact = require('fullcontact');
var fullcontact = new FullContact(apiKey);

Alternatively you can also use the provided createClient method, if that's how you roll.

var FullContact = require('fullcontact');
var fullcontact = FullContact.createClient(apikey);

Or just call it directly.

var fullcontact = require('fullcontact').createClient(apikey);

The initialized FullContact client will have some properties that you might find useful:

  • remaining The amount of API calls you have remaining
  • ratelimit The amount of API calls you're allowed to do
  • ratereset When your rate limit will be reset again in EPOCH

Please note that these properties are all set to 0 until you have made your first request to the API server as these values are parsed from the response headers.

Error responses

This API implementation will return an Error object when the FullContact response is returned without a status: 200 or status: 202 so it could be that your operation is queued for processing. That's why all returned error's have a status property which the returned status code (unless it's a parse error or a generic error). So just because you got an error, it doesn't mean that your request has failed.

Location

Turn your semi-structured data in fully structured location data. This Location endpoint is namespaced as a .location property. It has 2 optional arguments.

  1. casing How is the provided location cased?
  • uppercase for UPPERCASED NAMES (DENVER, COLORADO)
  • lowercase for lowercased names (denver, colorado)
  • titlecase for Title Cased names (Denver, Colorado)
  1. includeZeroPopulation will display 0 population census locations. The provided value should be a boolean.

fullcontact.location.normalize('denver', [casing], [includeZeroPopulation], fn);

Normalize the location data.

fullcontact.location.normalize('denver', function (err, data) {
  ..
});

With casing and includeZeroPopulation.

fullcontact.location.normalize('denver', 'uppercase', true, function (err, data) {
..
});

fullcontact.location.enrich('denver', [casing], [includeZeroPopulation], fn);

Retrieve more information from the location API.

fullcontact.location.enrich('denver', function (err, data) {
  ..
});

With casing and includeZeroPopulation.

fullcontact.location.enrich('denver', 'uppercase', true, function (err, data) {
..
});

Person

The Person endpoint is confidently namespaced as a .person property. Each person API has an optional queue argument which you can use to indicate that this request will be pre-processed by FullContact and that you want to fetch the details later. queue should be set to 1 to be enabled.

The following methods are available on this API:

person.email(address, [queue], [webhookUrl], [webhookId], fn);

Retrieves contact information by e-mail address.

fullcontact.person.email('[email protected]', function (err, data) {
  ..
});

All Person API's accept the queue param.

fullcontact.person.email('[email protected]', 1, function (err, data) {
..
});

Supports the use of webhooks by providing a callback url and an id. The id is only to track your webhooks and does nothing else.

fullcontact.person.email('[email protected]', null, 'https://mycallbackurl.com', 'webhooktracker', function (err, data) {
..
});

The Person API's now accept the macromeasures param as a boolean

fullcontact.person.email('[email protected]', null, null, null, null, null, true, function (err, data) {
  ..
});

person.md5(address, [queue], fn);

Retrieves contact information by e-mail address but transforms the email to an MD5 first.

fullcontact.person.md5('[email protected]', function (err, data) {
  ..
});

person.twitter(handle, [queue], fn);

Retrieves contact information by Twitter username.

fullcontact.person.twitter('3rdEden', function (err, data) {
  ..
});

person.phone(handle, [queue], fn);

Retrieves contact information by phone number.

fullcontact.person.phone('+13037170414', function (err, data) {
  ..
});

Email

Reduce the number of anonymous subscribers by detecting if the user is subscribing with a real e-mail address or just a one time address The Email endpoint is namespaced under the .email property.

email.disposable(email, fn);

Checks if the given e-mail address was disposable.

fullcontact.email.disposable('[email protected]', function (err, data) {
  ..
});

Name

The name API has an optional casing argument. The value of this optional argument can either be:

  • uppercase for UPPERCASED NAMES (JOHN SMITH)
  • lowercase for lowercased names (john smith)
  • titlecase for Title Cased names (John Smith)

fullcontact.name.normalize('John Smith', [casing], fn);

Normalize a name.

fullcontact.name.normalize('John Smith', function (err, data) {
  ..
});

Using casing.

fullcontact.name.normalize('John Smith', 'uppercase', function (err, data) {
..
});

fullcontact.name.deducer({ email: '[email protected]' }, [casing], fn);

Name deducing. Unlike other API's this API should receive an object with either an email or username property which you want to use to subtract the information.

fullcontact.name.deducer({ email: '[email protected]' }, function (err, data) {
  ..
});

fullcontact.name.deducer({ username: '3rdeden' }, 'lowercase', function (err, data) {
  ..
});

fullcontact.name.similarity('john', 'johnny', [casing], fn);

Check the similarity of between two names.

fullcontact.name.similarity('john', 'johnny', function (err, data) {
 ..
});

fullcontact.name.stats({ name: 'john' }, [casing], fn);

Retrieve some statistics about the name. Just like the name deducer API this API only accepts an object that receives either a givenName, familyName or both.

fullcontact.name.stats({ name: 'john' }, function (err, data) {
  ..
});

//
// fullcontact.name.stats({ givenName: 'john' }, [casing], fn);
// fullcontact.name.stats({ familyName: 'smith' }, [casing], fn);
// fullcontact.name.stats({ givenName: 'john', familyName: 'smith' }, [casing], fn);
//

fullcontact.name.parser('john smith', [casing], fn);

Parses the name to determine the likelihood that this is really a name.

fullcontact.name.parser('john smith', function (err, data) {
  ..
});

Company

Retrieve company info.

fullcontact.company.domain('fullcontact.com', [webhookUrl], [webhookId], fn);

Retrieve company info by domain.

fullcontact.company.domain('fullcontact.com', function (err, data) {
..
});

Supports the use of webhooks by providing a callback url and an id. The id is only to track your webhooks and does nothing else.

fullcontact.company.domain('fullcontact.com', null, 'https://mycallbackurl.com', 'webhooktracker', function (err, data) {
..
});

Batch

API requests can be grouped and sent into a single request.

fullcontact.multi();

Activates batch processing mode. The multi method returns a new FullContact API instance that's internally set to queuing. So all api endpoints you would hit are queued until you call the exec method.

As per the batch Process endpoint specs, up to 20 requests can be grouped in a batch.

fullcontact.exec();

Sends the batch request.

Example:

var multi = fullcontact.multi();

multi.person.facebook('arnout.kazemier', fn);
multi.person.facebook('john.appleseed', fn);

multi.exec(function (err) {
  console.log(err);
})

Testing

The CI testing happens with a free api key that has limits to the calls it can do to FullContact. If you see the tests fail make sure it is because of failing tests not exceeding rate limit.

The tests are written against the live FullContact API. They can be ran using:

API_KEY=<key> npm test

Don't worry if you forget it, we'll throw an error and let you know ;-).

License

The module is released under the MIT license.