Introduction
# Base URL
curl 'https://company.bigpicture.io'
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}'
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}'
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}'
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}'
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}'
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}'
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}'
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}'
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}'
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}'
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}'
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. |