Outscraper API Docs

/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.…

Businesses & POIBusiness Data API
↗ Open in API Explorer
POST

List Business Records

Businesses & POIBusiness Data API

Retrieve business records with optional enrichment data.

This endpoint provides access to millions of business listings with support for pagination and selective data enrichment. Choose which enrichments to include (contacts, emails, phone numbers, company insights, email verification, etc.) to optimize response size and cost.

Perfect for building lead lists, market research, or populating your CRM with verified business data.

Request

Endpoint: POST https://api.outscraper.cloud/businesses

Request Body Fields

FieldTypeRequiredDescriptionExampleConstraints
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.has_phone boolean No Whether the business has a phone number (true) or not (false). true -
filters.phone string No Phone number filter (partial or full match). 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.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. - -
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,
    "has_phone": true,
    "business_statuses": [
      "operational"
    ]
  },
  "limit": 10,
  "cursor": null,
  "include_total": false,
  "fields": [
    "name",
    "types",
    "address",
    "state",
    "postal_code",
    "country",
    "website",
    "phone",
    "rating",
    "reviews",
    "photo"
  ]
}

Responses

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.

{}

401

application/json

Wrong or missing API Key (token).

{
  "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.

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

422

application/json

Wrong query url parameters.

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

Related Endpoints

GETPOST
/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…

GoogleBusinesses & POI