/businesses

Retrieve business records with optional enrichment data. This endpoint provides access to millions of business listings with support for pagination and selective data enrichment.…

Open in API Explorer

POST

List Business Records

Request

Endpoint:

POST https://api.outscraper.com/businesses

Parameters

Responses

Field	Type	Required	Description	Example	Constraints
`filters`	object	No	Filtering criteria to narrow down business records.	-	-
`filters.os_ids`	array<string>	No	List of Outscraper business IDs (os_id) to include.	`[ "b3c1f2a0d9e84f0a6c3b9d2f4e7a1c90", "9f1a2b3c4d5e6f708192a3b4c5d6e7f8" ]`	-
`filters.os_ids[]`	string	No	-	-	-
`filters.country_code`	string	No	Two-letter country code to filter businesses by country (e.g., 'US', 'GB', 'CA').	`US`	-
`filters.states`	array<string>	No	List of states or provinces to filter businesses by.	`[ "CA", "NY" ]`	-
`filters.states[]`	string	No	-	-	-
`filters.cities`	array<string>	No	List of cities to filter businesses by.	`[ "Los Angeles", "New York" ]`	-
`filters.cities[]`	string	No	-	-	-
`filters.counties`	array<string>	No	List of counties/boroughs to filter businesses by.	`[ "Kings County", "Queens County" ]`	-
`filters.counties[]`	string	No	-	-	-
`filters.postal_codes`	array<string>	No	List of postal/ZIP codes to filter businesses by (full or partial).	`[ "10001", "90" ]`	-
`filters.postal_codes[]`	string	No	-	-	-
`filters.name`	string	No	Business name filter (partial or full match).	`Starbucks`	-
`filters.name_exclude`	boolean	No	Whether to exclude businesses matching the `name` filter (`true`) or include them (`false`).	`true`	-
`filters.types`	array<string>	No	List of business categories to include (e.g., 'restaurant', 'dentist', 'hotel').	`[ "restaurant", "cafe" ]`	-
`filters.types[]`	string	No	-	-	-
`filters.ignore_types`	array<string>	No	List of business categories to exclude from results.	`[ "bar", "night_club" ]`	-
`filters.ignore_types[]`	string	No	-	-	-
`filters.rating`	string	No	Rating filter expression.	`4.5+`	-
`filters.reviews`	string	No	Reviews count filter expression.	`100+`	-
`filters.has_website`	boolean	No	Whether the business has a website (`true`) or not (`false`).	`true`	-
`filters.domain`	string	No	Website domain to filter businesses by (e.g., 'example.com').	`example.com`	-
`filters.email_and_phone`	string enum	No	Filter by email and phone availability. Use `enter_phone` together with the `phone` field to match a specific phone number.	`with_phone`	allowed with_email, without_email, with_phone, without_phone, enter_phone, email_and_phone, email_or_phone
`filters.phone`	string	No	Phone number suffix to match when `email_and_phone` is `enter_phone`.	`14155550123`	-
`filters.business_statuses`	array<string enum>	No	Business status filter.	`[ "operational" ]`	-
`filters.business_statuses[]`	string enum	No	-	-	allowed operational, closed_temporarily, closed_permanently
`filters.added_from`	integer	No	Unix timestamp in seconds. Filters businesses added at or after this time.	`1717200000`	-
`filters.added_to`	integer	No	Unix timestamp in seconds. Filters businesses added at or before this time.	`1719791999`	-
`filters.updated_from`	integer	No	Unix timestamp in seconds. Filters businesses whose customer-visible data changed at or after this time.	`1717200000`	-
`filters.updated_to`	integer	No	Unix timestamp in seconds. Filters businesses whose customer-visible data changed at or before this time.	`1719791999`	-
`filters.area_service`	boolean	No	Whether the business is marked as an area service business.	`false`	-
`filters.verified`	boolean	No	Whether the business is verified.	`true`	-
`filters.geo_filters`	array<object>	No	List of geo filter objects (e.g., polygons, circles, bounding boxes).	`[ { "type": "circle", "lat": 34.0522, "lng": -118.2437, "radius_m": 2000 } ]`	-
`filters.geo_filters[]`	object	No	-	-	-
`filters.attributes`	array<string>	No	List of business attributes to filter by.	`[ "wheelchair_accessible", "takes_reservations" ]`	-
`filters.attributes[]`	string	No	-	-	-
`filters.located_os_id`	string	No	Location reference Outscraper ID used to filter nearby/related businesses.	`b3c1f2a0d9e84f0a6c3b9d2f4e7a1c90`	-
`filters.broad_match`	boolean	No	Whether to use broader matching for text/category filters.	`false`	-
`filters.business_only`	boolean	No	Whether to return only businesses (exclude other entity types).	`true`	-
`limit`	integer	No	Maximum number of business records to return.	-	min 1, max 1000, default 10
`cursor`	string \| null	No	Cursor for pagination to retrieve the next set of results.	-	-
`enrichments`	object	No	Enrichments to apply to business records.	-	-
`enrichments.leads_n_contacts`	object	No	Whether to include contacts and leads information in the response. This may include email addresses, phone numbers, and other contact details associated with the business.	`[ { "contacts_per_company": 5, "emails_per_contact": 3 } ]`	-
`enrichments.leads_n_contacts.contacts_per_company`	integer	No	Number of contacts to return per company when `leads_n_contacts` enrichment is enabled.	-	min 1, default 3
`enrichments.leads_n_contacts.emails_per_contact`	integer	No	Number of email addresses to return per contact when `leads_n_contacts` enrichment is enabled.	-	min 1, default 1
`enrichments.company_insights`	boolean	No	Whether to include company insights in the response. Company insights may include information such as estimated revenue, employee count, industry classification, and other relevant business metrics.	`true`	-
`query`	string \| null	No	Natural language query to search for businesses (e.g., `restaurants in New York`). This is an alternative to using structured filters and can be used in combination with them. The API will attempt to parse the query and apply relevant filters based on the content.	-	-
`include_total`	boolean	No	Whether to include the total count of matching records in the response. This could increase response time.	-	default false
`fields`	array<string>	No	List of fields to include in the response. If not specified, all fields will be returned.	`[ "name", "address", "website", "phone", "rating" ]`	-
`fields[]`	string	No	-	-	-

Request Example

{
  "filters": {
    "country_code": "US",
    "states": [
      "NY"
    ],
    "cities": [
      "New York",
      "Buffalo"
    ],
    "types": [
      "restaurant",
      "cafe"
    ],
    "has_website": true,
    "email_and_phone": "with_phone",
    "business_statuses": [
      "operational"
    ]
  },
  "limit": 10,
  "cursor": null,
  "include_total": false,
  "enrichments": {
    "leads_n_contacts": {
      "contacts_per_company": 3,
      "emails_per_contact": 1
    },
    "company_insights": {}
  }
}

200

application/json

The response contains the status of the request and data. Data is an array where each element represents a response for a single query from the request.

Response 200

{}

401

application/json

Wrong or missing API Key (token).

Response 401

{
  "error": true,
  "errorMessage": "401 Unauthorized: The server could not verify that you are authorized to access the URL requested. You either supplied the wrong credentials (e.g. a bad password), or your browser doesn't understand how to supply the credentials required."
}

402

application/json

Past due invoices or a payment method not connected.

Response 402

{
  "error": true,
  "errorMessage": "Please close past due invoices or verify your card information is correct."
}

422

application/json

Invalid query URL parameters.

Response 422

{
  "error": true,
  "errorMessage": "422 Unprocessable Entity: The request was well-formed but was unable to be followed due to semantic errors."
}

Code Samples

cURL

curl -X GET "https://api.outscraper.cloud/businesses/similar/outscraper.com" -H  "X-API-KEY: YOUR-API-KEY"

Related Endpoints

/bing-maps

Returns Bing Maps search results for one or more queries.

/booking-search

Returns search results from Booking.com

/businesses/{business_id}

Retrieve detailed information for a specific business by os id, place id, or google id, with optional enrichments. Returns a complete business profile including basic information…

/businesses/similar/{domain}

Find similar businesses based on a given domain. This endpoint allows you to discover businesses that are similar to a specified domain, which can be useful for competitive analys…

/expedia-search

Returns search results from expedia.com

/google-maps-search

Returns places from Google Maps based on a given search query (or many queries). The results from searches are the same as you would see by visiting a regular Google Maps site. Ho…