NAV
shell javascript
Docs Support Dashboard

Introduction

# Base URL
curl 'https://company.bigpicture.io'

Install the Node bindings using the bigpicture-node npm package.

npm install bigpicture-node

The BigPicture API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Our enrichment APIs include the Company API, to lookup company data by domain name, and the IP API, to lookup an IP address and return the company associated with that IP.

We currently support the following client libraries:

Authentication

Authentication by passing a token in an Authorization header:

curl 'https://company.bigpicture.io/v1/companies/find?domain=bigpicture.io' \
    -H 'Authorization: {API_KEY}'

import BigPicture from 'bigpicture-node';
const bigPicture = BigPicture('API_KEY');

// Or using commonjs modules
const bigpicture = require('bigpicture-node').default('api_key');

Authenticating with the APIs are accomplished through the use of an API key. You can find your key in the dashboard.

When accessing the APIs, include your API Key within the "Authorization" header of your request. An example of this is shown to the right.

Errors

Our API returns standard HTTP success or error status codes. For errors, we will also include extra information about what went wrong encoded in the response as JSON. The various HTTP status codes we might return are listed below.

HTTP Status codes

Code Title Description
200 OK The request was successful.
202 Async created The resource was asynchronously created
400 Bad request Bad request
401 Unauthorized Your API key is invalid.
402 Over quota Over plan quota on this endpoint.
404 Not found The resource does not exist.
429 Too Many Requests The rate limit was exceeded.
50X Internal Server Error An error occurred with our API.

Error Types

{
  "error": {
    "type": "bad_request",
    "message": "Bad Request"
  }
}
Error Code Meaning
async_created Your request has been received. Try this request again in a few minutes.
bad_request Your request is invalid.
not_found The record was not found.
rate_limit Too many requests made to the API too quickly.
api_error An error occurred internally with BigPicture's API.

Rate Limiting

Example rate limit error response.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1624665413

All API requests are currently subject to rate limits of 600 requests per minute, apart from the streaming APIs that are set to 5 requests per minute. If you need a higher limit, email us and we can discuss it further.

Header Name
X-RateLimit-Limit The maximum number of requests that the consumer is permitted to make per minute.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.

Webhooks and Streaming

Our system works by doing a real-time search of various sources and doing a deep analysis of the data before returning a final result. Thus if a result is not already in our database or needs to refreshed, a real-time search can take some time before the data is ready. So there are couple different methods available for you to consider.

Default Lookup

The default functionality is to return a 200 status with the data if it's in our database. Otherwise, if we need to do a search, we will return an 202 status. You can then either poll the endpoint, or make another request in a few minutes once we've had some time to process the data.

Webhooks

Webhook request example

curl 'https://company.bigpicture.io/v1/companies/find?domain=bigpicture.io&webhookUrl=https://requestb.in/wpyz2mwp&webhookId=12345' \
  -H 'Authorization: {API_KEY}'

import BigPicture from 'bigpicture-node';
const bigPicture = BigPicture('API_KEY');
const Company = bigPicture.Company;
Company.find({
    domain: 'bigpicture.io',
    webhookUrl: 'https://requestb.in/wpyz2mwp',
    webhookId: 12345
})
  .then(company => console.log(company))
  .catch(error => console.error(error));

Webhook response

{
  "id": "Your optional webhook id",
  "status": 200,
  "type": "company",
  "body": {
    "name": "BigPicture.io",
    "description": "The easiest way to get advanced website analytics without writing any code.",
    "category": {
        "sector": "Technology",
        "industry": "Software & Computer Services",
        "subIndustry": "Internet",
        "industryGroup": "Technology"
    },
    "//": "..."
  }
}

Webhooks are a mechanism that allow you to supply a URL to the API that we can send data to once an operation is complete.

Webhooks are defined in the request parameters using the webhookUrl field. You can also provide an optional webhookId parameter to link up requests and will be included in the final response.

When a webhook has been provided for a given request, an HTTP POST request will be sent to the URL provided once the process has completed. The payload of the POST request will be sent as JSON and include the following parameters.

Parameter Description
id string
An optional field to help link requests.
status integer
Either a 200 code (success) or 404 (we couldn't find the data).
type string
The type of resource. Currently company.
body object
The company data

Streaming

Streaming request example

curl 'https://company.bigpicture.io/v1/companies/find/stream?domain=bigpicture.io' \
  -H 'Authorization: {API_KEY}'

import BigPicture from 'bigpicture-node';
const bigPicture = BigPicture('API_KEY');
const Company = bigPicture.Company;
Company.find({
    domain: 'bigpicture.io',
    stream: true
})
  .then(company => console.log(company))
  .catch(error => console.error(error));

An alternative to using webhooks is our streaming API. This API is ideal if you don’t mind long lived requests (e.g. you’re making requests to BigPicture from a messaging queue).

Requests made to the streaming API will never return a HTTP 202 status response, and can be held open for up to a 200 seconds.

The only difference between making calls to the normal and streaming API is the path - company.bigpicture.io/v1/companies/find/stream rather than company.bigpicture.io/v1/companies/find.

Company API

The Company API enables you to lookup company data based on a domain name. This can be used to retrieve the company's information such as name, address, industry, headcount, and various other details from their domain name.

API billing is tracked by unique call per 30 day period. So if you didn't cache the data or need to re-process a list of requests, those requests won't count against your quota.

Attributes

The dot notation indicates that the field is one level deep inside the object. If we can’t find data for an attribute, then we’ll set a null value.

{
    "id": "4eec624c-c1b4-43c5-9a91-c96859353ccc",
    "name": "Uber Technologies",
    "legalName": "Uber Technologies, Inc.",
    "domain": "uber.com",
    "url": "https://www.uber.com/",
    "logo": "http://logo.bigpicture.io/logo/uber.com",
    "type": "public",
    "phone": "1-415-801-4068",
    "ticker": "UBER",
    "tags": [
        "B2C",
        "Logistics",
        "Mobile Apps",
        "Public Transportation",
        "Ride Sharing",
        "Transportation"
    ],
    "tech": [
        "facebook_connect",
        "facebook_custom_audiences",
        "google_analytics",
        "tealium",
        "visier",
        "time_tap",
        "the_muse",
        "when_i_work",
        "supersourcing",
        "workday_benefits",
        "pardot",
        "quick_base",
        "dialpad_sell",
        "salesforce_crm",
        "salesforce_mobile",
        "xant_formerly_inside_sales",
        "qzzr",
        "brand_24",
        "monday_com",
        "movable_ink",
        "never_bounce",
        "crowd_analyzer",
        "shopify",
        "big_cartel",
        "productsup",
        "woo_commerce",
        "awesome_data",
        "cerner",
        "gympass",
        "collibra",
        "one_login",
        "cisco_asa",
        "global_models",
        "amazon_inspector",
        "live_ramp_identity_link",
        "wrike",
        "smartsheet",
        "microsoft_word",
        "amazon_workspaces",
        "microsoft_powerpoint",
        "oomnitza",
        "azure_sql",
        "automate_io",
        "jira_software",
        "jira_service_desk",
        "oracle_asset_lifecycle_management",
        "truly",
        "exotel",
        "twilio",
        "web_rtc",
        "genesys",
        "serenova",
        "j_unit",
        "mockito",
        "bugzilla",
        "circle_ci",
        "perfecto",
        "optimizely",
        "ha_proxy",
        "cisco_2960",
        "dell_laptop",
        "cisco_meraki",
        "cisco_open_dns",
        "cisco_3800_series_routers",
        "ansys",
        "harvest",
        "clockify",
        "solidworks",
        "toggl_track",
        "adobe_illustrator",
        "camtasia",
        "agile_crm",
        "survey_gizmo",
        "google_forms",
        "marketo_forms",
        "zendesk_support",
        "ui_path",
        "oracle_ebs",
        "workday_projects",
        "manhattan_centerstone",
        "nginx",
        "datadog",
        "tableau_software",
        "azure_blob_storage",
        "google_cloud_functions",
        "amazon_web_services_aws",
        "siemens_plm",
        "siemens_teamcenter",
        "you_tube",
        "balsamiq",
        "wordpress",
        "amazon_ec_2",
        "spring_cloud",
        "first_data",
        "quick_books",
        "travel_perk",
        "adp_streamline",
        "quick_books_online",
        "adp_smart_compliance",
        "impact",
        "fleetio",
        "docu_sign",
        "duolingo",
        "opti_signs",
        "dat_solutions",
        "alteryx",
        "chartio",
        "hive_ai",
        "azure_machine_learning",
        "golang",
        "tornado",
        "java_script",
        "microsoft_azure",
        "google_dialogflow",
        "kubernetes_native"
    ],
    "aliases": [
        "Uber",
        "UberCab",
        "UberCab.com"
    ],
    "description": "Uber Technologies, Inc. develops and operates proprietary technology applications in the United States, Canada, Latin America, Europe, the Middle East, Africa, and the Asia Pacific. It connects consumers with independent providers of ride services for ridesharing services; and connects riders and other consumers with restaurants, grocers, and other stores with delivery service providers for meal preparation, grocery, and other delivery services. The company operates through three segments: Mobility, Delivery, and Freight. The Mobility segment provides products that connect consumers with mobility drivers who provide rides in a range of vehicles, such as cars, auto rickshaws, motorbikes, minibuses, or taxis. It also offers financial partnerships, transit, and vehicle solutions offerings. The Delivery segment allows consumers to search for and discover local restaurants, order a meal, and either pick-up at the restaurant or have the meal delivered; and offers grocery, alcohol, and convenience store delivery, as well as select other goods. The Freight segment connects carriers with shippers on the company's platform and enable carriers upfront, transparent pricing, and the ability to book a shipment, as well as transportation management and other logistics services offerings. The company was formerly known as Ubercab, Inc. and changed its name to Uber Technologies, Inc. in February 2011. Uber Technologies, Inc. was founded in 2009 and is headquartered in San Francisco, California.",
    "foundedYear": 2009,
    "domainAliases": [
        "ubermovement.com",
        "health.uber.com",
        "uber-adsystem.com"
    ],
    "emailProvider": false,
    "metrics": {
        "raised": 25212450000,
        "employees": 32600,
        "marketCap": 49321758720,
        "trancoRank": 785,
        "alexaUsRank": 540,
        "annualRevenue": 29048000512,
        "employeesRange": "10K+",
        "alexaGlobalRank": 1076,
        "estimatedAnnualRevenue": "$10B+"
    },
    "category": {
        "sector": "Technology",
        "industryGroup": "Technology",
        "industry": "Software & Computer Services",
        "subIndustry": "Software",
        "naicsCode": "485999"
    },
    "location": "1515 3Rd Street San Francisco, CA 94158 United States of America",
    "geo": {
        "streetNumber": "1515",
        "streetName": "3Rd Street",
        "subPremise": null,
        "city": "San Francisco",
        "state": "California",
        "postalCode": "94158",
        "stateCode": "CA",
        "country": "United States of America",
        "countryCode": "US"
    },
    "facebook": {
        "handle": "uber"
    },
    "linkedin": {
        "handle": "company/uber-com",
        "industry": "software development"
    },
    "twitter": {
        "id": "19103481",
        "bio": "Go with ease ➡️ Go with friends ➡️ Go with confidence ➡️ Go anywhere 🚗 \n\nFor customer support contact @Uber_Support",
        "site": "https://linktr.ee/uber",
        "avatar": "https://pbs.twimg.com/profile_images/1045783102000230400/TPLLaqYR_normal.jpg",
        "handle": "Uber",
        "location": "Global",
        "followers": 1088753,
        "following": 46
    },

    "crunchbase": {
        "handle": "organization/uber"
    },
    "indexedAt": "2023-01-13T17:20:14.250Z"
}
Attribute Description
id string
Internal ID
domain string
Domain name of company
name string
Name of company
legalName string
Legal name of company
domainAliases array
Other domains associated with company
url string
Primary website url
tags array
A list of descriptive tags to describe company (see options)
category.sector string
Top level sector to categorize company industry (see options)
category.industryGroup string
Industry group (see options)
category.industry string
Industry (see options)
category.subIndustry string
Sub industry (see options)
category.naicsCode string
NAISC Code
description string
The best description we have of the company
foundedYear integer
Founding year of company
location string
Formatted address of company
geo.streetNumber string
Primary office street number
geo.streetName string
Primary office street name
geo.subPremise string
Primary office suite number
geo.city string
Primary office normalized city
geo.state string
Primary office normalized state
geo.stateCode string
Primary office normalized two letter state code
geo.country string
Primary office normalized country
geo.countryCode string
Primary office normalized two letter state code
metrics.trancoRank integer
The Tranco ranking of the domain
metrics.alexaUsRank integer
The US Alexa ranking of the domain
metrics.alexaGlobalRank integer
The global Alexa ranking of the domain
metrics.employees integer
Approximate number of employees at company
metrics.employeesRange string
Approximate employee range at company
metrics.marketCap integer
Company's market capitalization
metrics.annualRevenue integer
Company's approximate annual revenue
metrics.estimatedAnnualRevenue string
Company's approximate annual revenue range
metrics.raised string
Company's approximate amount of funding raised
tech array
Detected technology used by company
facebook.handle string
The Facebook handle of Company's page
linkedin.handle string
The LinkedIn handle
linkedin.industry string
The LinkedIn industry
twitter.handle string
The Twitter handle
twitter.id string
Twitter ID
twitter.bio string
Twitter bio
twitter.followers integer
Count of Twitter followers
twitter.following integer
Count of Twitter friends
twitter.location string
Twitter location
twitter.site string
Twitter website
twitter.avatar string
Twitter URL avatar
crunchbase.handle string
Crunchbase handle
logo string
URL logo for the company
emailProvider boolean
Whether or not this domain is an email provider (gmail.com, comcast.net, etc.)
type string
The company type, which is either public, private, nonprofit, or government
ticker string
The ticker symbol the company is traded under
phone string
The primary phone number of company
indexedAt string
When this record was last indexed

Lookup

The Company API is designed to look up a company via their domain name. We also support a few other options that may help in the lookup process.

The supported parameters are:

curl 'https://company.bigpicture.io/v1/companies/find?domain=uber.com' \
  -H 'Authorization: {API_KEY}'

import BigPicture from 'bigpicture-node';
const bigPicture = BigPicture('API_KEY');
const Company = bigPicture.Company;
Company.find({domain: 'uber.com'})
  .then(company => console.log(company))
  .catch(error => console.error(error));
Parameter Description
domain string (required)
The domain to lookup.
webhookUrl string
A webhook URL the results will be sent to.
webhookId string
An optional identifier for webhook request.

HTTP Request

When the webhookUrl parameter is included, we will make a POST call to the url you provide when processing is complete.

 curl 'https://company.bigpicture.io/v1/companies/find?domain=uber.com&webhookUrl=https://requestb.in/wpyz2mwp' \
  -H 'Authorization: {API_KEY}'

import BigPicture from 'bigpicture-node';
const bigPicture = BigPicture('API_KEY');
const Company = bigPicture.Company;
Company.find({
    domain: 'uber.com',
    webhookUrl: 'https://requestb.in/wpyz2mwp'
})
  .then(company => console.log(company))
  .catch(error => console.error(error));

When you make a request, the default behavior is to return a 200 status with the data. If the data is not yet in our database or stale we will return an empty 202 status. You can either try the request again in a few minutes, stream the request, or provide a webhook URL we should call when the data is ready.

You can also include an optional webhookId, which will be included with the response data. It's useful if you have a single webhook endpoint and want to match up results to an internal id.

curl 'https://company.bigpicture.io/v1/companies/find?domain=uber.com&webhookUrl=https://requestb.in/wpyz2mwp&webhookId=12345' \
-H 'Authorization: {API_KEY}'

import BigPicture from 'bigpicture-node';
const bigPicture = BigPicture('API_KEY');
const Company = bigPicture.Company;
Company.find({
    domain: 'uber.com',
    webhookUrl: 'https://requestb.in/wpyz2mwp',
    webhookId: 12345
})
  .then(company => console.log(company))
  .catch(error => console.error(error));

Responses

Code Description
200 - OK A match has been found.
202 - Accepted Occurs when email is not yet in our database or the data is stale.
404 - Not Found We could not find a match.

Streaming

Stream example

curl 'https://company.bigpicture.io/v1/companies/find/stream?domain=bigpicture.io' \
  -H 'Authorization: {API_KEY}'

import BigPicture from 'bigpicture-node';
const bigPicture = BigPicture('API_KEY');
const Company = bigPicture.Company;
Company.find({
    domain: 'uber.com',
    stream: true
})
  .then(company => console.log(company))
  .catch(error => console.error(error));

Our system works by doing a real-time search of various sources and doing a deep analysis of the data before returning a final result. If you'd prefer, you can hold the connection open and wait until the data is ready by calling the stream endpoint.

Please note, this endpoint currently has a lower rate limit of 5 requests per min. If you need a higher rate limit, please contact us.

Name to Domain API (BETA)

The Name to Domain API enables you to turn a company name into a domain name. It's powered by a machine learning model to predict the best match for the company name. If needed, you can then use the returned domain to call the Company API to lookup the company data for the domain.

API billing is tracked per request for the 30 day billing period.

Attributes

The dot notation indicates that the field is one level deep inside the object. If we can’t find data for an attribute, then we’ll set a null value.

{
    "data": [
        {
            "name": "Google",
            "domain": "google.com",
            "confidence": 1
        },
        {
            "name": "Google UK",
            "domain": "google.co.uk",
            "confidence": 0.51
        },
        {
            "name": "Google Germany GmbH",
            "domain": "google.de",
            "confidence": 0.45
        }
    ],
    "totalCount": 3
}
Attribute Description
name string
Name of company
domain string
Domain name of company
confidence float
Confidence score of match between 0-1.

Returns

A object with a data property that contains an array of up to 3 matching results. Each entry in the array is a separate match result object. If there are no matches, the API will throw a 404 status code error.

Lookup

The Name to Domain API is designed to look up a company via their name.

The supported parameters are:

NOTE: This API is not yet supported via the Javascript SDK.

curl 'https://company.bigpicture.io/v2/companies/search?name=Google' \
  -H 'Authorization: {API_KEY}'

curl 'https://company.bigpicture.io/v2/companies/search?name=Google' \
  -H 'Authorization: {API_KEY}'
Parameter Description
name string (required)
The company name to lookup.

HTTP Request

 curl 'https://company.bigpicture.io/v2/companies/search?name=Google' \
  -H 'Authorization: {API_KEY}'

curl 'https://company.bigpicture.io/v2/companies/search?name=Google' \
  -H 'Authorization: {API_KEY}'

When you make a request, the default behavior is to return a 200 status with the data or a 404 status if we can't find a good match.

Responses

Code Description
200 - OK A match has been found.
404 - Not Found We could not find a match.

IP API

The IP API takes an IP address and returns the company associated with that IP, also known as IP to company. This can be used for identifying website traffic for sales & marketing, analytics, and personalization.

This API is built through a combination of public and proprietary data sources that identifies companies by IP regardless of their size. We support both IPv6 and IPv4 adddres.

API billing is tracked by unique call per 30 day period. So if you didn't cache the data or need to re-process a list of requests, those requests won't count against your quota.

Attributes

The dot notation indicates that the field is one level deep inside the object. If we can’t find data for an attribute, then we’ll set a null value.

{
    "ip": "204.4.143.118",
    "type": "business",
    "fuzzy": false,
    "confidence": 0.95,
    "geo": {
        "city": "London",
        "state": "England",
        "stateCode": "ENG",
        "country": "United Kingdom",
        "countryCode": "GB",
        "continent": "Europe",
        "continentCode": "EU",
        "isEU": true
    },
    "company": {
        "id": "535384f0-e5f0-4a5c-9aeb-339e8304e18f",
        "domain": "goldmansachs.com",
        "name": "Goldman Sachs Group",
        "legalName": "The Goldman Sachs Group, Inc.",
        "logo": "http://logo.bigpicture.io/logo/goldmansachs.com",
        "url": "https://www.goldmansachs.com/",
        "tags": [
            "Finance",
            "Financial Services",
            "FinTech"
        ],
        "//": "..."
    },
    "whois": {
        "domain": "ny.email.gs.com",
        "name": "The Goldman Sachs Group, Inc."
    },
    "asn": {
        "asn": "AS9084",
        "name": "European AS",
        "route": "204.4.143.0/24"
    }
}
Attribute Description
ip string
IP address that was requested
type string
The type of result (business, isp, hosting).
confidence float
The confidence score of the matched company on a scale between 0-1.
fuzzy boolean
False if the company has their own dedicated ASN block or WHOIS record, otherwise true.
geo.city string
City that this IP is located in
geo.state string
State that this IP is located in
geo.stateCode string
State code for this IP’s state
geo.country string
Country that this IP is located in
geo.countryCode string
Country code for this IP’s country
geo.continent string
Continent that this IP is located in
geo.continentCode string
Continent code for this IP’s continent
geo.isEU boolean
Whether this IP is located in the European Union (EU)
company object
The company data associated with the IP. Refer to our Company API documentation for schema information.
whois.domain string
Domain associated with the WHOIS record
whois.name string
Organization name associated with the WHOIS record
asn.asn string
The Autonomous System Number (ASN)
asn.name string
Organization name associated with the ASN record
asn.route string
The subnet for the ASN record

Lookup

The IP API is designed to transform an IP to company profile.

curl 'https://ip.bigpicture.io/v2/companies/ip?ip=204.4.143.118' \
  -H 'Authorization: {API_KEY}'

import BigPicture from 'bigpicture-node';
const bigPicture = BigPicture('API_KEY');
const Ip = bigPicture.Ip;
Ip.find({ip: '204.4.143.118'})
  .then(response => console.log(response))
  .catch(error => console.error(error));
Parameter Description
ip string (required)
The IP address to lookup.

HTTP Request

curl 'https://ip.bigpicture.io/v2/companies/ip?ip=204.4.143.118' \
  -H 'Authorization: {API_KEY}'

import BigPicture from 'bigpicture-node';
const bigPicture = BigPicture('API_KEY');
const Ip = bigPicture.Ip;
Ip.find({ip: '204.4.143.118'})
  .then(response => console.log(response))
  .catch(error => console.error(error));

When you make a request, the default behavior is to return a 200 status with the data.

Responses

Code Description
200 A match has been found.
404 We could not find a match.
500 We encountered an error looking up the company.
shell javascript