Overview

The ReviewData API operates through a streamlined five-step process for efficient review data collection:

Obtain Your API Key - Secure your essential authentication credentials.
Configure Webhooks - Establish notification mechanisms for request completion.
Submit Review Request - Initiate review data collection by sending business details.
Receive Webhook Notifications - Get notified upon the successful completion of your review data request.
Retrieve Review Data - Access and download the collected review data.

Step 1: Obtain Your API Key

Request API Key

To begin, navigate to our dedicated API key request page: Request API Key ->

Subsequent Actions

An onboarding email will be sent to you, containing your unique API key.
This API key is mandatory for all subsequent API requests.
Ensure the security of your API key and refrain from public disclosure.

Step 2: Configure Webhooks

The Importance of Webhooks

Webhooks provide real-time notifications upon the completion of your review collection requests, eliminating the need for continuous API polling for status updates.

Webhook Endpoint Configuration

Endpoint: POST https://data.reviewdata.ai/webhooks/create-webhook/

Request Payload:

{
  "api_key": "YOUR_API_KEY_HERE",
  "webhook": "https://webhook.site/28facfba-ae3f-40a1-8730-f69ea2ad2c4a"
}

Parameters:

api_key: Your unique API key, as provided in the onboarding email.
webhook: The URL designated to receive notifications (must be publicly accessible).

Response:

{
    "webhook": "https://webhook.site/28facfba-ae3f-40a1-8730-f69ea2ad2c4a",
    "status": "success"
}

Webhook Implementation Guidelines

Verify that your webhook endpoint supports POST requests.
Respond with a 200 HTTP status code to acknowledge receipt of the notification.
Implement robust error handling mechanisms for potential webhook failures.
For enhanced security, consider implementing webhook signature verification.

Step 3: Submit Review Request

Endpoint

POST https://data.reviewdata.ai/submit/request-reviews/

Request Payload Structure

{
  "job": "App\Jobs\RequestReviews",
  "data": {
    "lazy": true,
    "api_key": "YOUR_API_KEY_HERE",
    "business": {
      "id": "unique_business_id",
      "name": "Business Name",
      "tags": ["tag1", "tag2"],
      "phone": "+1234567890",
      "address": {
        "zip": "12345",
        "city": "City Name",
        "state": "State",
        "street": "Street Address",
        "country": "Country"
      },
      "description": "Business description"
    },
    "publishers": {
      "maps.google.com": {
        "profile_key": "https://maps.google.com/...",
        "first_page_only": false,
        "last_review_hashes": []
      }
    },
    "foreign_key": "your_unique_identifier"
  }
}

🚧
CRITICAL REQUEST LIMITATIONS
Each API request is restricted to targeting a single review platform at a time.
This implies:

✅ Permitted: A single request to retrieve reviews from Google Maps for McDonald's.

❌ Not Permitted: A single request to retrieve reviews from Google Maps, Yelp, and TripAdvisor for McDonald's concurrently.

For obtaining data from multiple platforms, distinct requests must be submitted:

Request 1: McDonald's reviews from Google Maps

Request 2: McDonald's reviews from Yelp

Request 3: McDonald's reviews from TripAdvisor

Example: To acquire review data from five different platforms (e.g., Google Maps, Yelp, TripAdvisor, Facebook) for the same business location, you are required to submit five individual API requests.

📘
PROFILE KEY AND COST IMPLICATIONS
Definition of a Profile Key: **The profile_key represents the direct URL to your business listing on a specific review platform (e.g., your Google Maps business URL, Yelp business page URL).
Cost Impact Assessment:

✅ Providing theprofile_key: Standard pricing applies (you are billed solely for review data extraction).

❌ Omitting theprofile_key: Standard pricing applies, in addition to an extra business search fee.

Operational Flow:

✅ Withprofile_key provided: You furnish the exact business URL → We proceed with review extraction → You incur the standard rate.

❌ Withoutprofile_key provided: You supply the business name/address → We identify your business URL → We proceed with review extraction → You incur the standard rate plus the supplementary search fee.

💰 Cost Efficiency: Always endeavor to include the profile_key in your requests and retain it for subsequent use to mitigate additional search expenses.

Key Parameters Elucidated

Business Object

id: A unique identifier for the business within your internal system.
name: The official name of the business.
tags: An optional array categorizing the business.
phone: The primary contact phone number for the business.
address: Comprehensive address details for the business location.
description: An optional textual description of the business.

Publishers Object

This object facilitates the configuration of review data collection from specified review platforms:

Google Maps Example:

"maps.google.com": {
  "profile_key": "https://www.google.com/maps/place/...",
  "first_page_only": false,
  "last_review_hashes": []
}

Yelp Example:

"yelp.com": {
  "profile_key": "https://www.yelp.com/biz/...",
  "first_page_only": true,
  "last_review_hashes": []
}

TripAdvisor Example:

"tripadvisor.com": {
  "profile_key": "https://www.tripadvisor.com/...",
  "first_page_only": true,
  "last_review_hashes": []
}

Publisher Parameters

profile_key: The direct URL to the business's profile on the review platform (optional; the system can locate it).
first_page_only: Set to true to retrieve only the first page of reviews; false to retrieve all available reviews.
last_review_hashes: An array of review hashes utilized to prevent the collection of duplicate entries. Maximum last 4 review's hash.

Other Parameters

lazy: Set to true for large-scale review collections, which may entail extended processing times.
foreign_key: Your unique identifier for tracking this specific request.
api_key: Your authentication key.

Response

{
    "status": "success",
    "tasks_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
    "request_id": "9f9d2b5a-085c-4df3-bcca-20928f086925",
    "foreign_key": "TEST_1751004113518_i6yxcl",
    "publisher_key": "maps.google.com",
}

Response Fields:

status: Indicates the submission status of the request.
request_id: A unique identifier for tracking the overall request.
tasks_id: A unique identifier for the specific task.
foreign_key: Your original identifier associated with the request.
publisher_key: The review site from which data was processed.

Step 4: Receive Webhook Notifications

Webhook Payload Structure

Upon the completion of your request, a webhook notification will be delivered with the following structure:

{
    "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
    "publisher_key": "maps.google.com",
    "foreign_key": "TEST_1751004113518_i6yxcl",
    "profile_key": "https://www.google.com/maps/place/@40.7094789,-74.0126167,886m/data=!3m2!1e3!5s0x89c2592f4977ef97:0xf78d57398ac93494!4m7!3m6!1s0x89c25a177d4bf5db:0x84e51f23e8c0a75c!8m2!3d40.7094789!4d-74.0100364!10e1!16s%2Fg%2F1thtf190!5m1!1e1?entry=ttu&g_ep=EgoyMDI1MDY",
    "task_status": 200,
    "reviews_urls": [
        "https://prod-data-only-client.s3.amazonaws.com/Review_URLs/9f9d2b5a-085c-4df3-bcca-20928f086925/900e2ff4-2d25-4576-ab18-b9b8e73c0bd6_0.jl"
    ]
}

Webhook Fields Explained

task_id: The unique identifier for the completed task.
publisher: The review site that was processed.
foreign_key: Your original identifier associated with the request.
profile_key: The URL of the business profile utilized for the task.
task_status: The HTTP status code indicating the task's outcome (200 signifies success).
reviews_urls: An array of URLs where the collected review data is securely stored.

Step 5: Retrieve Review Data

Endpoint

POST https://data.reviewdata.ai/retrieve-task/

Request Payload

{
  "api_key": "YOUR_API_KEY_HERE",
  "page": 1,
  "page_size": 10,
  "task_id": "your_task_id",
  "foreign_key": "your_unique_identifier",
  "publisher_key": "publisher_name"
}

Parameters

api_key: Your authentication key.
foreign_key: The identifier you supplied during the initial request submission.
publisher_key: The specific review site (e.g., "maps.google.com").
page: The desired page number for paginated results.
page_size: The number of reviews to be returned per page.
task_id: This task_id is provided upon the successful submission of the review request.

Response Structure

{
    "foreign_key": "TEST_1751004113518_i6yxcl",
    "batch_id": "TEST_1751004113518_i6yxcl",
    "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
    "related_task_ids": [],
    "task_status": 200,
    "business": {
        "publisher": "maps.google.com",
        "profile_key": "https://www.google.com/maps/place/@40.7094789,-74.0126167,886m/data=!3m2!1e3!5s0x89c2592f4977ef97:0xf78d57398ac93494!4m7!3m6!1s0x89c25a177d4bf5db:0x84e51f23e8c0a75c!8m2!3d40.7094789!4d-74.0100364!10e1!16s%2Fg%2F1thtf190!5m1!1e1?entry=ttu&g_ep=EgoyMDI1MDY",
        "reviews_urls": [
            "https://prod-data-only-client.s3.amazonaws.com/Review_URLs/9f9d2b5a-085c-4df3-bcca-20928f086925/900e2ff4-2d25-4576-ab18-b9b8e73c0bd6_0.jl"
        ],
        "id": "restaurant_001",
        "name": "McDonald's",
        "tags": [
            "restaurant",
            "pizza",
            "italian",
            "casual"
        ],
        "phone": "+12123852066",
        "address": {
            "zip": "10038",
            "city": "New York",
            "state": "NY",
            "street": "160 Broadway",
            "country": "USA"
        },
        "description": "Classic, long-running fast-food chain known for its burgers & fries."
    },
    "reviews": [
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT25wVFEzWkxPR1ZJYkdWS04zWjNlWEo2ZW01UVZGRRAB",
            "author_name": "Regimorais Raab",
            "author_id": null,
            "rating": 5,
            "text": "Rapidez incrível",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT25wVFEzWkxPR1ZJYkdWS04zWjNlWEo2ZW01UVZGRRAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOnpTQ3ZLOGVIbGVKN3Z3eXJ6em5QVFE%7C0cLUo1-b2qC%7C?hl=en",
            "posted_at": 1750727938010,
            "review_hash": "f2601fda3fb2e249204ff97d9710acd7",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT2pFeFEzSXpjVW8zZUdkalFYQkRiR2hSV2xWdVIzYxAB",
            "author_name": "gloria schuweiler",
            "author_id": null,
            "rating": 3,
            "text": "Some  how they  been getting  my order wrong.",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT2pFeFEzSXpjVW8zZUdkalFYQkRiR2hSV2xWdVIzYxAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOjExQ3IzcUo3eGdjQXBDbGhRWlVuR3c%7C0cLP3KjBeBa%7C?hl=en",
            "posted_at": 1750704405791,
            "review_hash": "3de49930bb5221fce5bb352146649726",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT2t0bVYyODNNRUo2VWxCMVVGcGhRVGxtYzBKNUxXYxAB",
            "author_name": "Zadran Akram khan",
            "author_id": null,
            "rating": 2,
            "text": "Happy Wellcomen New And Last Chef Akram Zadran",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT2t0bVYyODNNRUo2VWxCMVVGcGhRVGxtYzBKNUxXYxAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOktmV283MEJ6UlB1UFphQTlmc0J5LWc%7C0cKzlVRIta5%7C?hl=en",
            "posted_at": 1750596704474,
            "review_hash": "c11d5ca37c28d429beb161013fdd2c3d",
            "language": "en"
        },
        {
            "review_id": "ChZDSUhNMG9nS0VLUHNodGJuc18ycFR3EAE",
            "author_name": "Ivana Donev",
            "author_id": null,
            "rating": 4,
            "text": "",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChZDSUhNMG9nS0VLUHNodGJuc18ycFR3EAE!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CIHM0ogKEKPshtbns_2pTw%7CCgwI8oq2wgYQsPr9wQE%7C?hl=en",
            "posted_at": 1749910898406,
            "review_hash": "d7f32bfcdd9e46b23f04b2d69e1fe373",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT214TVVHTjNWMkZzVjFSMlQzQmhSMVoyYWtKZmRuYxAB",
            "author_name": "Ludovic Pagès",
            "author_id": null,
            "rating": 2,
            "text": "C'est déjà le bas du panier en France, ben ce n'est pas mieux sur Broadway à Wall Street. Je ne comprends pas pour quoi ça existe encore. Pour le reste ce resto a un service rapide et des toilettes propres.",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT214TVVHTjNWMkZzVjFSMlQzQmhSMVoyYWtKZmRuYxAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOmxMUGN3V2FsV1R2T3BhR1Z2akJfdnc%7C0cI7yCrlChX%7C?hl=en",
            "posted_at": 1749847949935,
            "review_hash": "56848456ebc3393b5aa98a3134242221",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT20xS1UyWjRNR2hLTUdRd2RERmlVVXd4VDFOblgyYxAB",
            "author_name": "Aaron Moore",
            "author_id": null,
            "rating": 5,
            "text": "",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT20xS1UyWjRNR2hLTUdRd2RERmlVVXd4VDFOblgyYxAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOm1KU2Z4MGhKMGQwdDFiUUwxT1NnX2c%7C0cI4FOfmJHX%7C?hl=en",
            "posted_at": 1749832729734,
            "review_hash": "ce4e8f08dbe2fda5d996cf906b553450",
            "language": "en"
        },
        {
            "review_id": "ChZDSUhNMG9nS0VQX3FpdmVkMHBhSlNREAE",
            "author_name": "Cevdet S A",
            "author_id": null,
            "rating": 5,
            "text": "Like it.",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChZDSUhNMG9nS0VQX3FpdmVkMHBhSlNREAE!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CIHM0ogKEP_qived0paJSQ%7CCgsI5p2pwgYQqMTXfA%7C?hl=en",
            "posted_at": 1749700326261,
            "review_hash": "433aa5e69074d92921cdac0b848ec3fd",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT2pZelVUQTVVRkp3YVhGa1lUTlBVVk42VWxGcE9GRRAB",
            "author_name": "Vinod Sukhadia",
            "author_id": null,
            "rating": 5,
            "text": "",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT2pZelVUQTVVRkp3YVhGa1lUTlBVVk42VWxGcE9GRRAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOjYzUTA5UFJwaXFkYTNPUVN6UlFpOFE%7C0cHNU251Vof%7C?hl=en",
            "posted_at": 1749649347101,
            "review_hash": "aa0b25c137f7b386a6d392f91b54b5e0",
            "language": "en"
        },
        {
            "review_id": "ChZDSUhNMG9nS0VPM0E4N2k4a2V6SEJ3EAE",
            "author_name": "Husnain Ali",
            "author_id": null,
            "rating": 4,
            "text": "",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChZDSUhNMG9nS0VPM0E4N2k4a2V6SEJ3EAE!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CIHM0ogKEO3A87i8kezHBw%7CCgwI4c2jwgYQ2Mjj1wE%7C?hl=en",
            "posted_at": 1749608161452,
            "review_hash": "b7e33c65de9262919ad22741f0554832",
            "language": "en"
        },
        {
            "review_id": "ChdDSUhNMG9nS0VJQ0FnSURwX3QtdHJBRRAB",
            "author_name": "Fred Alluso",
            "author_id": null,
            "rating": 4,
            "text": "Clean, noisy, crowded. Most importantly they didn't mess up my coffee order.",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChdDSUhNMG9nS0VJQ0FnSURwX3QtdHJBRRAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CIHM0ogKEICAgIDp_t-trAE%7C0cMTWPpdFWz%7C?hl=en",
            "posted_at": 1692756313115,
            "review_hash": "924067883b209b62d4ffd556179d9634",
            "language": "en"
        }
    ],
    "pagination": {
        "total_reviews": 11820,
        "page": 1,
        "page_size": 10,
        "total_pages": 1182,
        "has_next": true,
        "has_previous": false
    }
}

Review Data Fields

review_id: A unique identifier assigned to each review.
author_name: The name of the reviewer.
author_id: The unique identification for the reviewer.
rating: The assigned rating for the review, ranging from 1 to 5.
text: The complete content of the review.
url: A direct link to the original review on the platform.
posted_at: The Unix timestamp (in UTC) indicating when the review was published.
review_hash: A unique hash value used for deduplication purposes.
language: The language code of the review.

Best Practices

Performance Optimization

Utilize lazy: true for businesses associated with a substantial volume of reviews.
Implement appropriate pagination strategies to manage extensive datasets effectively.
Store review_hash values to prevent the collection of redundant data.

Error Handling

Consistently verify API response status codes.
Implement robust retry logic for webhook notifications.
Manage API rate limits with graceful degradation.

Data Management

Maintain a record of profile_key URLs to circumvent additional business matching costs.
Employ descriptive foreign_key values to facilitate efficient request tracking.
Implement comprehensive data validation prior to submission.

Security

Safeguard API keys rigorously and rotate them periodically.
Validate webhook url and it should be functional.
Ensure all webhook endpoints utilize HTTPS for secure communication.

Now that you understand the complete flow: