DataForSEO
SEO, search-engine results, keyword research, backlinks and AI visibility data.
Live Business Listings Search Tasks
Searches DataForSEO's own index of local business listings by categories, description, title and location_coordinate - a latitude, longitude and radius triple. Returns total_count, count, offset, offset_token and items, paged with the token. Wrapped in DataForSEO's envelope: data in tasks[0].result, outcome in tasks[0].status_code - a rejected request still returns HTTP 200. This reads an index and answers immediately; everything else here queues a live scrape of the source. Start with this and drill in only where it matters.
Pricing reference
- Metering: Reported response cost.
- Reference request estimate: USD 0.2428.
- Reference customer multiplier: 1.0. Do not apply it again to a settled customer amount.
Reference metadata only, not an account quote, a guaranteed price or a spending cap. Resource credits are not Felo credits. Final charges follow Felo billing records.
- Type: array (object | null)[]
- categoriesType: array string[] | null
business categories
optional field
the categories you specify are used to search for business listings;
if you don't use this field, we will return business listings found in the specified location;
you can specify up to 10 categories - descriptionType: string | null
description of the element in SERP
optional field
the description of the business entity for which the results are collected;
can contain up to 200 characters - filtersType: array (object | null)[] | null
array of results filtering parameters
optional field
you can add several filters at once (8 filters maximum)
you should set a logical operatorand,orbetween the conditions
the following operators are supported:regex,not_regex,<,<=,>,>=,=,<>,in,not_in,like,not_like,ilike,not_ilike,match,not_match
you can use the%operator withlikeandnot_liketo match any string of zero or more characters
example:["rating.value",">",3]
you can receive the list of available filters_by making a separate request tohttps://api.dataforseo.com/v3/business_data/business_listings/available_filters
The full list of possible filters is available here.nEmpty object - isType: boolean | null
_claimed indicates whether the business is verified by its owner on Google Maps
optional field - limitType: integer | null
the maximum number of returned businesses
optional field
default value:100
maximum value:1000 - locationType: string | null
_coordinate GPS coordinates of a location
optional fieldlocation_coordinateparameter should be specified in the "latitude,longitude,radius" format
the maximum number of decimal digits for "latitude" and "longitude": 7
the value of "radius" is specified in kilometres (km)
the minimum value for "radius":1
the maximum value for "radius":100000
example:53.476225,-2.243572,200
learn more about how to set location parameters in this API on our Help Center - offsetType: integer | null
offset in the results array of returned businesses
optional field
default value:0
if you specify the10value, the first ten entities in the results array will be omitted and the data will be provided for the successive entities
Note: we recommend using this parameter only when retrieving up to 10,000 results
for retrieving over 10,000 results, use theoffset_tokeninstead - offsetType: string | null
_token token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the uniqueoffset_tokenvalue from the response array, you will get the subsequent results of the initial task;offset_tokenvalues are unique for each subsequent task
Note: if theoffset_tokenis specified in the request, all other parameters should be identical to the previous request
learn more about this parameter on our Help Center - orderType: array string[] | null
_by results sorting rules
optional field
you can use the same values as in thefiltersarray to sort the results
possible sorting types:asc- results will be sorted in the ascending orderdesc- results will be sorted in the descending order
you should use a comma to set up a sorting parameter
example:["rating.value,desc"]note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example:["rating.value,desc","rating.votes_count,desc"] - tagType: string | null
user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specifiedtagvalue in thedataobject of the response - titleType: string | null
title of the element in SERP
optional field
the name of the business entity for which the results are collected;
can contain up to 200 characters
- Type: object | null · Response36Afe1097B20_BusinessDataBusinessListingsSearchLiveResponseInfo200
- Type: number | null Format: doublecost
total tasks cost, USD
- Type: integer | nullstatus
_code general status code you can find the full list of the response codes here
- Type: string | nullstatus
_message general informational message you can find the full list of general informational messages here
- Type: array (object | null)[] | nulltasks
array of tasks
- Type: object | null · Response36Afe1097B20_BusinessDataBusinessListingsSearchLiveTaskInfo
- costType: number | null Format: double
total tasks cost, USD
- dataType: object | null
contains the same parameters that you specified in the POST request
- propertyType: object | null
Name
- idType: string | null
task identifier unique task identifier in our system in the UUID format
- pathType: array (string | null)[] | null
URL path
- resultType: array (object | null)[] | null
array of results
- countType: integer | null Format: int64
item types
the number of items in theitemsarray - itemsType: array (object | null)[] | null
encountered item types
types of search engine results encountered in theitemsarray;
possible item types:business_listing- additionalType: array (string | null)[] | null
_categories additional business categories
additional Google My Business categories that describe the services provided by the business entity in more detail - addressType: string | null
address of the business entity
- addressType: object | null · Response36Afe1097B20_AddressInfo
_info object containing address components of the business entity
- addressType: string | null
street address of the local establishment
- boroughType: string | null
administrative unit or district the local establishment belongs to
- cityType: string | null
name of the city where the local establishment is located
- countryType: string | null
_code ISO country code of the local establishment
- regionType: string | null
DMA region the local establishment belongs to
- zipType: string | null
ZIP code of the local establishment
- attributesType: object | null · Response36Afe1097B20_BusinessDataAttributesInfo
service details in a form of user-reviewed checks;
service details of a business entity displayed in a form of checks and based on user feedback and businesscategory- availableType: object | null
_attributes available attributes
indicates attributes a business entity can offer- propertyType: array (string | null)[] | null
Name
- unavailableType: object | null
_attributes unavailable attributes
indicates attributes a business entity cannot offer- propertyType: array (string | null)[] | null
Name
- categoryType: string | null
business category
Google My Business general category that best describes the services provided by the business entity - categoryType: array (string | null)[] | null
_ids global category IDs
universal category IDs that do not change based on the selected country - checkType: string | null
_url direct URL to search engine results
you can use it to make sure that we provided accurate results - cidType: string | null
- contactType: array (object | null)[] | null
_info available contacts of the business
list of contacts to interact with the business- sourceType: string | null
data source
- typeType: string | null
type of element
- valueType: string | null
the value of the rating
- descriptionType: string | null
description of the element in SERP
the description of the business entity for which the results are collected - domainType: string | null
domain of the business entity
- featureType: string | null
_id - firstType: string | null
_seen date and time when our crawler found the business listing element for the first time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2023-03-11 10:04:11 +00:00 - hotelType: integer | null
_rating - isType: boolean | null
_claimed shows whether the entity is verified by its owner on Google Maps
- lastType: string | null
_updated _time date and time when the data was last updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example:2023-01-26 09:03:15 +00:00 - latitudeType: number | null
latitude coordinate of the local establishments in google maps
example:"latitude": 51.584091 - localType: array (object | null)[] | null
_business _links available interactions with the business
list of options to interact with the business directly from search results- typeType: string | null
type of element
- logoType: string | null
URL of the logo featured in Google My Business profile
- longitudeType: number | null
longitude coordinate of the local establishment in google maps
example:"longitude": -0.31365919999999997 - mainType: string | null
_image URL of the main image featured in Google My Business profile
- originalType: string | null
_title original title of the element
original title not translated by Google - peopleType: array (object | null)[] | null
_also _search related business entities
- cidType: string | null
- featureType: string | null
_id - ratingType: object | null · Response36Afe1097B20_RatingInfo
the element's rating
the popularity rate based on reviews and displayed in SERP- ratingType: integer | null
_max the maximum value for a rating_type
- ratingType: string | null
_type the type of rating here you can find the following elements: Max5, Percents, CustomMax
- valueType: number | null Format: double
the value of the rating
- votesType: integer | null Format: int64
_count the amount of feedback
- titleType: string | null
title of the element in SERP
the name of the business entity for which the results are collected
- phoneType: string | null
phone number of the business entity
- placeType: string | null
_id unique place identifier
place id of the local establishment featured in the element
learn more about the identifier in this help center article - placeType: object | null
_topics keywords mentioned in customer reviews
contains most popular keywords related to products/services mentioned in customer reviews of a business entity and the number of reviews mentioning each keyword
example:
"place_topics": {
"egg roll": 48,
"birthday": 33
}- propertyType: integer | null Format: int64
Name Signed 64-bit integers (long type).
- popularType: object | null · Response36Afe1097B20_PopularTimes
_times popular times
information related to busy hours of the business entity- popularType: object | null
_times _by _days popular hours
information about busy hours of the local establishment on each day of the week- propertyType: array (object | null)[] | null
Name work hours on Sundays
- popularType: integer | null
_index popularity index relative time-bound popularity index measured from 0 to 100; higher value corresponds to a busier time of a day
- timeType: object | null · Response36Afe1097B20_TimeInfo
hours in the 24-hour format
- hourType: integer | null
hours in the 24-hour format
- minuteType: integer | null
minutes
- priceType: string | null
_level property price level
can take values:inexpensive,moderate,expensive,very_expensive
if there is no price level information, the value will benull - ratingType: object | null · Response36Afe1097B20_RatingInfo
the element's rating
the popularity rate based on reviews and displayed in SERP- ratingType: number | null Format: double
_max the maximum value for a rating_type
- ratingType: string | null
_type the type of rating here you can find the following elements: Max5, Percents, CustomMax
- valueType: number | null Format: double
the value of the rating
- votesType: integer | null Format: int64
_count the amount of feedback
- ratingType: object | null
_distribution the distribution of ratings of the business entity
the object displays the number of 1-star to 5-star ratings, as reviewed by users- propertyType: integer | null Format: Int64
Name
- servicesType: array (object | null)[] | null
- categoryType: string | null
business category
Google My Business general category that best describes the services provided by the business entity - priceType: object | null · Response36Afe1097B20_PriceInfo
- currencyType: string | null
currency of the listed price ISO code of the currency applied to the price
- currentType: number | null Format: double
current price indicates the current price of the product or service featured in the result
- displayedType: string | null
_price price string in the result raw price string as provided in the result
- isType: boolean | null
_price _range price is provided as a range indicates whether a price is provided in a range
- maxType: number | null Format: double
_value the maximum price the maximum price of the product or service as indicated in the result
- regularType: number | null Format: double
regular price indicates the regular price of the product or service with no discounts applied
- snippetType: string | null
additional information on the business entity
- titleType: string | null
title of the element in SERP
the name of the business entity for which the results are collected
- snippetType: string | null
additional information on the business entity
- titleType: string | null
title of the element in SERP
the name of the business entity for which the results are collected - totalType: integer | null Format: int64
_photos total count of images featured in Google My Business profile
- typeType: string | null
type of element
- urlType: string | null
absolute url of the business entity
- workType: object | null · Response36Afe1097B20_BusinessWorkHoursInfo
_time work time details
information related to operational hours of the business entity- workType: object | null · Response36Afe1097B20_WorkHours
_hours open hours
information about work hours of the local establishment- currentType: string | null
_status current status of the establishment
indicates whether the establishment is opened or closed - timetableType: object | null
work hours timetable
- propertyType: array (object | null)[] | null
Name work hours on Sundays
- closeType: object | null · Response36Afe1097B20_TimeInfo
closing time
- hourType: integer | null
hours in the 24-hour format
- minuteType: integer | null
minutes
- openType: object | null · Response36Afe1097B20_TimeInfo
opening time
- hourType: integer | null
hours in the 24-hour format
- minuteType: integer | null
minutes
- offsetType: integer | null Format: int64
Signed 64-bit integers (long type).
- offsetType: string | null
_token - totalType: integer | null Format: int64
_count total number of results in our database relevant to your request
- resultType: integer | null Format: int64
_count number of elements in the result array
- statusType: integer | null
_code status code of the task generated by DataForSEO, can be within the following range: 10000-60000 you can find the full list of the response codes here
- statusType: string | null
_message informational message of the task you can find the full list of general informational messages here
- timeType: string | null
execution time, seconds
- Type: integer | null Format: int64tasks
_count the number of tasks in the tasks array
- Type: integer | null Format: int64tasks
_error the number of tasks in the tasks array returned with an error
- Type: string | nulltime
total execution time, seconds
- Type: string | nullversion
the current version of the API
application/json - 400
The request could not be processed. Check the request parameters.
- 401
A valid Felo API key is required.
- 402
The request cannot proceed because a billing requirement is not met.
- 403
The account is not permitted to perform this operation.
- 429
A request or spending limit has been reached.
- 502
The service could not complete the request.
- 503
The API or billing service is temporarily unavailable.
- 504
The service timed out while processing the request.
- default
Error response; upstream passthrough responses may use provider formats
application/json
curl https://openapi.felo.ai/v1/beta/dataforseo/business_data/business_listings/search/live \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '[
{
"categories": [
"pizza_restaurant"
],
"description": "pizza",
"title": "pizza",
"is_claimed": true,
"location_coordinate": "53.476225,-2.243572,10",
"order_by": [
"rating.value,desc"
],
"filters": [
[
"rating.value",
">",
3
]
],
"limit": 3
}
]'
{
"version": null,
"status_code": null,
"status_message": null,
"time": null,
"cost": null,
"tasks_count": null,
"tasks_error": null,
"tasks": [
{
"id": null,
"status_code": null,
"status_message": null,
"time": null,
"cost": null,
"result_count": null,
"path": [
null
],
"data": null,
"result": [
{
"total_count": null,
"count": null,
"offset": null,
"offset_token": null,
"items": [
{
"type": null,
"title": null,
"original_title": null,
"description": null,
"category": null,
"category_ids": [
"[Max Depth Exceeded]"
],
"additional_categories": [
"[Max Depth Exceeded]"
],
"cid": null,
"feature_id": null,
"address": null,
"address_info": "[Max Depth Exceeded]",
"place_id": null,
"phone": null,
"url": null,
"domain": null,
"logo": null,
"main_image": null,
"total_photos": null,
"snippet": null,
"latitude": null,
"longitude": null,
"is_claimed": null,
"attributes": "[Max Depth Exceeded]",
"place_topics": null,
"rating": {
"0": "[",
"1": "M",
"2": "a",
"3": "x",
"4": " ",
"5": "D",
"6": "e",
"7": "p",
"8": "t",
"9": "h",
"10": " ",
"11": "E",
"12": "x",
"13": "c",
"14": "e",
"15": "e",
"16": "d",
"17": "e",
"18": "d",
"19": "]",
"rating_type": "[Max Depth Exceeded]",
"value": "[Max Depth Exceeded]",
"votes_count": "[Max Depth Exceeded]",
"rating_max": "[Max Depth Exceeded]"
},
"hotel_rating": null,
"price_level": null,
"rating_distribution": null,
"people_also_search": [
"[Max Depth Exceeded]"
],
"work_time": "[Max Depth Exceeded]",
"popular_times": "[Max Depth Exceeded]",
"local_business_links": [
"[Max Depth Exceeded]"
],
"contact_info": [
"[Max Depth Exceeded]"
],
"check_url": null,
"last_updated_time": null,
"first_seen": null,
"services": [
"[Max Depth Exceeded]"
]
}
]
}
]
}
]
}