Contents:
-
Expansion of parameters
-
What is to be done with the token after receiving it?
-
What request should be sent to BrandWizard to get all the reviews?
- Creating custom reviews
- Is it possible to send custom reviews via API to an inactive company in the BrandWizard personal account?
-
Pagination through pages with reviews
-
Changing the display of the number of reviews on the page
-
Filtering reviews
-
Filtering by date_gte and date_lte
-
Filtering by catalog_id
-
Filtering by company_id
-
Filtering by brand_id
-
-
Sending a response to a review using the api
-
What request should be sent to BrandWizard to be able to complain about the review?
- What problems may arise when getting a rating on Yandex?
-
What problems may arise when getting a rating on Google?
-
Why are there no photos from Google reviews?
-
Why have the reviews not been transmitted via the API?
-
Why has the API not sent a complaint about the review to Google?
-
How to edit a response to a review via the API?
-
What is Requests per minute (RPM)?
-
What will happen if permissible PRM 60 is exceeded?
-
What is to be done if the BrandWizard service returns a response to the request: {“detail“: “The request was ignored. Expected available in 47 seconds.“}?
Expansion of parameters
-
brand_id - brand ID in BrandWizard. The list of brands with their IDs can be obtained using the GET /public/v1/brands/ method.
-
company_id - company ID in BrandWizard. The list of companies with their IDs can be obtained using GET /public/v1/companies/ method.
-
id - ID (for instance: brand, company, review, question, answer).
-
url - address of the site/page (for instance, pages with reviews in the catalog).
-
text - text content data (for instance: response to a review, question, review).
-
notes - a note on the review.
-
rating - review rating.
-
rating_count - the number of ratings. Based on this parameter, we provide:
-
- Rating (Yandex, 2GIS, Google).
- Number of ratings (ONLY for Yandex and 2GIS).
- Number of reviews (Yandex, 2GIS, Google).
-
-
author - name of the author of the review/ question/response.
-
brand_page_url - address of the page with brand reviews (Yandex, Facebook).
-
website - location of the server content.
-
datetime - date and time (for instance: of review creation, deletion).
-
created_in_catalog - date of creation in the catalog.
-
created_in_rd - date the review was created in the BrandWizard database.
-
parsed_at - date of the last review parsing from the catalog.
-
comment - review text.
-
deleted_at - date the review was deleted in the catalog.
-
able_to_reply - ability to respond to a review.
-
origin_url - link to the location of the review in the catalog.
-
location_url - link to the location from which the reviews were collected.
-
able_to_abuse - ability to leave complaints.
-
abuse_last_date - date of the last review left via the BrandWizard api.
-
is_changed - the review has been changed or not (the review is considered changed if its text or rating has changed).
-
tags - list of tags.
-
catalog_id - catalog id in BrandWizard (google maps, yandex maps, 2gis (URBI), etc.).
-
company - information on the company that has been reviewed.
-
brand - brand information.
-
children - list of responses to the review.
Children fields -
author - author of the response.
-
created_in_catalog - date the response was created in the catalog.
-
created_in_rd - date the response was created in the BrandWizard database.
-
parsed_at - date of the last parsing of the response from the catalog.
-
comment - response text.
-
deleted_at - response creation date.
-
able_to_reply - ability to respond to an answer.
-
type - response type (reply/command).
-
reply_id - response id in BrandWizard (the reply_id and command_id fields cannot be filled in at the same time. The reply_id field will be filled in when the response is collected from the catalog and saved to the BrandWizard database).
-
command_id - command id in BrandWizard (the reply_id and command_id fields cannot be filled in at the same time. The command_id field will be filled in at the moment when the user writes a response to the review and sends it either via api (https://api.brandwizard.io/public/swagger-ui/#/Reviews%20v4/v4_reviews_reply_create), or through the BrandWizard personal account. When the response is published in the catalog and collected, the command_id will become empty and the reply_id field will be displayed).
-
is_company_comment - official response of the company or not.
-
able_to_edit - ability to edit the response.
-
able_to_delete - ability to delete a response.
-
user - user in BrandWizard who left the response.
What is to be done with the token after receiving it?
-
Follow the link: https://api.brandwizard.io/public/swagger-ui/.
-
To log in to the documentation page, click the Authorize button.
-
In the window that appears, enter Token XXX in the value field.
-
Click on Authorize.
What request should be sent to BrandWizard to get all the reviews?
You need to make a GET request to the api https://api.brandwizard.io/public/v4/reviews.
In response you will receive a JSON with a list of reviews.
Creating custom reviews
To create a custom review, use the POST method.
- origin_url — link to the customer's review.
- creation_time — date and time of the review creation.
- phone — phone number of the customer who left the review.
- user_fields — here you can specify additional information that you need, such as email.
"user_fields": {
"email": "test@email.com"
}Is it possible to send custom reviews via API to an inactive company in the BrandWizard personal account?
If a company is inactive, you have a public API license and access to that company, you can create, edit, and delete(mark deleted) custom reviews.
To do this, you need to make a request using the POST method.
Pagination through pages with reviews
In the body of the next key response there is a link to the next page.
To get to the next page, you need to make a GET request at the link https://go.brandwizard.io/public/v4/reviews/?cursor=bHQ9MjAyMy0w0C0yMisxMCUzQTUzJTNBMTg%3D&per_page=10.
To return to the previous page, you need to take the link that is located by the previous key and make a GET request.
Changing the display of the number of reviews on the page
By default, 30 reviews per page are displayed. To show more, you need to specify the per_page parameter in query params by entering the required number of reviews.
Example:
Make a GET request at the link http://api.brandwizard.io/public/v4/reviews/?per_page=100.
Filtering reviews
-
process_status – reviews processing statuses. You can add this field to the query, but there will be no such filed in the response for public api.
-
created_at_gt – when this filter is used, the response will contain reviews with the date of review creation in BrandWizard older than the passed date.
Filtering by date_gte and date_lte
-
date_gte is a filter after the specified date of review creation in the catalog (inclusive).
-
date_lte is a filter before the specified date of review creation in the catalog (inclusive).
The time passing from the review creation in the catalog to its appearance in the BrandWizard is different for each service, because there is moderation in the source. However, if the review is present on the maps, it will appear in the personal area within a day. -
These dates are linked to the time zone UTC 0.
Let's consider the following situation:
A process of getting reviews from API for the previous day is launched on 01:30 every day, i.e. date_gte=[yesterday] date_lte=[yesterday] respectively are transferred to the parameters date_gte / date_lte.
The review was created in the catalog on 27.03 at 23:58:00 and appeared in the BrandWizard 3 hours later – on 28.03 at 02:58:00.
Collection process starts on 28.03 at 01:30 with parameters date_gte=2023-03-27 date_lte=2023-03-27 – the said review does not go into the response because it is not yet in BrandWizard.
Collection process starts on 29.03 at 01:30 with parametrs date_gte=2023-03-28 date_lte=2023-03-28 -- the said review does not go into the response: it is already in the BrandWizard, but it does not meet the filters date_gte/date_lte.
This situation is theoretically possible:
Reviews with rating or text changed will fall under the has_changes filter. The field parsed_at is not related to the filters date_gte and date_lte, as they sort by created_in_catalog. The field parsed_at will be changed, i.e. the date when the review was last time collected from the catalog.
Suppose the review created_in_catalog=2023-04-05T16:58:00, created_in_bw=2023-04-05T17:58:00, parsed_at=2023-04-05T17:58:00. Full collection will start in a day, created_in_catalog и created_in_rd remain unchanged, parsed_at changes to 2023-04-06 at 17:58:00. If at any moment the text, rating, or both is changed for a review in the catalog, the response will contain the changed rating, text, or both, and created_in_catalog will remain the same, unless the catalog itself has a logic that when a review is changed, the date of its creation is changed. In your example, if the review created_in_catalog 27.03, and your collections starts on 29.03 from date_gte=2023-03-28 date_lte=2023-03-28, this review will not appear in the response.
Accordingly, in the following situations:
-
If the review was initially created in BrandWizard on 2023-03-15 at 4:00:00, and a new response appeared on 2023-03-18 at 14:00:00, such review will not go into the response to the review with the parameter created_at_gt=2023-03-18T00:00:00.
-
If the review was initially created in BrandWizard on 2023-03-15 at 14:00:00, and then changed on 2023-03-18 at 14:00:00, such review will not go into the response to the review with the parameter created_at_gt=2023-03-18T00:00:00.
Filtering by catalog_id
There is a catalog_id parameter in the body of the review. For instance, catalog_id = 2.
To find out which catalog_id corresponds to which catalog, you need to make a request to the api with sources https://api.brandwizard.io/public/v1/catalogs/ (https://api.brandwizard.io/public/swagger-ui/#/Catalog/v1_catalogs_list).
The parameters for filtering catalogs can be found here.
To filter reviews by a specific catalog, you need to specify the catalog_ids parameter in query params and make a GET request. You can specify a list of catalogs by listing them separated by commas.
Example of a link for filtering by catalog:
http://api.brandwizard.io/public/v4/reviews?catalog_ids=11,12,2.
Filtering by company_id
To get a list of companies that you have access to, you need to make a GET request to the following api https://api.brandwizard.io/public/v1/companies/. You can read about filtering companies here.
To filter reviews by company, you need to specify the company_ids parameter in query params, then make a GET request at the link, for instance, http://api.brandwizard.io/public/v4/reviews/?company_ids=95737.
Filtering by brand_id
To get a list of brands that you have access to, you need to make a GET request to the following api https://api.brandwizard.io/public/v1/brands/. You can read about filtering brands here.
To filter reviews by brand, you need to specify the brand_ids parameter in query params and the brand list, then make a GET request at the link, for instance, http://api.brandwizard.io/public/v4/reviews/?brand_ids=7067.
You can read about the other parameters with which you can filter brands here.
Sending a response to a review using the api
When a response to a review is sent via the BrandWizard api, the first step is to create a command. If you request the review with its id, then a record in relation to it will appear in children. If the command_id field is filled in, and the reply_id field is empty, this means that the command is displayed, not the response. The command will go to the catalog. A response to the review is created in the catalog. This response is collected from the catalog and added to the BrandWizard database. After that, if you request a review again, to which a response was left, then the command_id field in children will become empty, and the response id will appear in the reply_id field.
Example:
example of a link for sending responses to a review http://api.brandwizard.io/public/v4/reviews/{review_id}/reply/.
The following JSON is contained in the request body:
{
"comment":"comment text"
}
For instance, there is a review with id=102755165. For this review, you need to leave a response. The link will look like this https://api.brandwizard.io/public/v4/reviews/102755165/reply/.
The following JSON is contained in the request body:
{
"comment":"Thanks for comment"
}
You need to make a request using the POST method.
The response will return code 200. And the body of the response will contain JSON with the json response command
{
"reply_id": null,
"command_id": command id,
"type": "command",
"author": null,
"comment": reply text,
"created_in_rd": created in BrandWizard database,
"created_in_catalog": null,
"parsed_at": null,
"deleted_at": null,
"is_company_comment": true,
"is_autoreply": is it made with autoreplies (true/false),
"able_to_reply": ability to give a reply to a reply(true/false),
"able_to_edit":ability to edit reply(true/false),
"able_to_delete": ability to delete reply(true/false),
"children": [],
"user": {
"id": 39561,
"email": email of the user who has given a reply,
"first_name": first name of the user who has given a reply,
"last_name": last name of the user who has given a reply,
"full_name": full name of the user who has given a reply
}
}
When a request for this review is made again, review_id =102755165, then in addition to the body of the review, the command json will appear in children.
{
"author": comment author,
"created_in_catalog": date of creation in catalog,
"created_in_rd": date of creation in BrandWizard database,
"parsed_at": comment collection date,
"comment": comment text,
"deleted_at": comment deletion date, for deleted comment,
"able_to_reply": ability to reply to a reply,
"id": comment id,
"rating": rating,
"origin_url": link to comment location in catalog,
"location_url": link to location the comments were collected from,
"able_to_abuse": ability to leave complaints to comment,
"abuse_last_date": last complaint date,
"is_changed": comment changed or not,
"tags": tags,
"catalog_id": catalog id,
"company": {
"id": company id,
"name": company name,
"address": {
"country": city,
"country_code": country code,
"region": region,
"city": city,
"street": street,
"housenumber": house number,
"postcode": postal code
}
},
"brand": {
"id": brand id,
"name": brand name,
"is_test": test brand ot not
},
"children": [
{
"author": author,
"created_in_catalog": date of creation in catalog,
"created_in_rd": date of creation in BrandWizard database,
"parsed_at": "2022-05-17T09:25:17.445041Z",
"comment": comment text,
"deleted_at": reply deletion date,
"able_to_reply": ability to give a reply to a reply,
"type": reply/command type,
"reply_id": reply id,
"command_id": command id,
"is_company_comment": company’s official reply,
"is_autoreply": replied by autoreply,
"able_to_edit": ability to edit reply,
"able_to_delete": ability to delete reply,
"user": {
"id": id of the user who has given a reply,
"email": email of the user who has given a reply,
"first_name": first name of the user who has given a reply,
"last_name": last name of the user who has given a reply,
"full_name": full name of the user who has given a reply
},
"children": []
}
]
},
The rest of the methods for working with responses can be found here in the Reviews v4 section.
What request should be sent to BrandWizard to be able to complain about the review?
-
First you need to make a request: https://api.brandwizard.io/public/v4/reviews/public/v4/reviews/{id}/abuse/.
-
In the id field , specify the review id.
-
In the Request body, communicate the reason parameter with the complaint text.
What problems may arise when getting a rating on Yandex?
To obtain ratings for catalogs, a ccl request is used via the link https://api.brandwizard.io/public/v1/ccl/.
Problems when obtaining a rating can occur for the following reasons:
- Location is not synchronized.
- There are no reviews in Yandex, hence no rating.
What problems may arise when getting a rating on Google?
This can happen for the following reasons:
-
Location not confirmed in Google Business Profile.
-
There are no reviews in Google, and there is no rating, respectively.
Why are there no photos in Google reviews?
There are no photos in the Google API. As soon as such an opportunity appears, it will be possible to transfer photos in reviews.
Why have the reviews not been transmitted via the API?
The API transmits the information that is available in the BrandWizard personal account. That is, for instance, if reviews are not transmitted via the API, and they are not in the BrandWizard personal account - this is not an API error, we need to deal separately with the reason for the lack of reviews in the personal account.
Why has the API not sent a complaint about the review to Google?
From our service, we send a complaint only to 2gis (URBI) and Yandex reviews. You can read more about how to send a complaint about a review from your BrandWizard personal account here.
How to edit a response to a review via the API?
Editing responses to reviews is available in Google and Facebook (if the response left not through the personal account is the official response of the company) and Yandex (except for branded reviews and if the response, left not through a personal account, is an official response of the company).
There are two options:
1. Edit the response to a review that has not yet been delivered.
-
First you need to make a request: https://api.brandwizard.io/public/v4/reviews/{review_id}/commands/{command_id}/.
-
In the review_id field, specify the review id.
-
In the command_id field,specify the command id.
-
In the Request body communicate the comment parameter with the text of the new response.
2. Edit the response to a review that has already been delivered.
-
First you need to make a request: https://api.brandwizard.io/public/v4/reviews/{review_id}/replies/{reply_id}/.
-
In the review_id field, specify the review id.
-
In reply_id, specify the response id.
-
In the Request body communicate the comment parameter with the text of the new response.
Example of a request for reviews:
curl -X GET "https://api.brandwizard.io/public/v4/reviews/?count=10&page=1" -H "accept: application/json" -H "Authorization: Token”. In Token, you must specify your token.
What is Requests per minute (RPM)?
Requests per minute (RPM) is the speed limit of requests sent from the user. Determined by the number of requests per minute.
What will happen if the permissible PRM 60 is exceeded?
If the permissible PRM 60 is exceeded, the system will show error “HTTP_429_TOO_MANY_REQUESTS“.
What is to be done if the BrandWizard service returns a response to the request: {“detail“: “The request was ignored. Expected available in 47 seconds.“}?
You can filter reviews for a certain period of time date_lte date_gte in query params, and also transmit catalog_ids=12 to get reviews from a specific catalog (In this case, Yandex).