Response Models

The Response Models define the structure of data returned by the ReviewData Lite API endpoints.

Success Response Model

Schema

{
    "status": "string",
    "tasks_id": "string",
    "request_id": "string",
    "foreign_key": "string",
    "publisher_key": "string",
}

Fields

Field	Type	Description
`status`	string	Status of the request (usually "success")
`tasks_id`	string (UUID)	Scraping task's id
`request_id`	string (UUID)	Unique identifier for the request
`foreign_key`	string	External request identifier
`publisher_key`	string	Review publisher/platform (e.g., "maps.google.com")

Example

{
    "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",
}

Task Response Model

Schema

{
  "foreign_key": "string",
  "batch_id": "string",
  "task_id": "string",
  "related_task_ids": [],
  "task_status": integer,
  "business": {
      "publisher": "string",
      "profile_key": "string",
      "reviews_urls": ["string"],
      "id": "string",
      "name": "string",
      "tags": ["string"],
      "phone": "string",
      "address": {
          "zip": "string",
          "city": "string",
          "state": "string",
          "street": "string",
          "country": "string"
      },
      "description": "text"
  },
  "reviews": [
    {
      "review_id": "string",
      "author_name": "string",
      "author_id": "string",
      "rating": "integer",
      "text": "string",
      "url": "string",
      "posted_at": "integer",
      "source_date": "string",
      "scraped_at": "integer",
      "review_hash": "string",
      "language": "string"
    }
  ],
  "pagination": {
    "total_reviews": "integer",
    "page": "integer",
    "page_size": "integer",
    "total_pages": "integer",
    "has_next": "boolean",
    "has_previous": "boolean"
  }
}

Fields

Field	Type	Description
`task_id`	string	Unique task identifier
`response_message`	array	Array of task status messages
`foreign_key`	string	Your original foreign key
`reviews`	array	Array of review objects (only for completed tasks)
`pagination`	object	Pagination information (only for completed tasks)

Response Message Object

Field	Type	Description
`task_id`	string	Unique task identifier
`publisher`	string	Publisher name (e.g., "maps.google.com")
`foreign_key`	string	Your original foreign key
`profile_key`	string	Business profile URL
`task_status`	integer	Task status code
`reviews_urls`	array	Array of S3 URLs containing review data

Review Object

Field	Type	Description
`review_id`	string	Unique review identifier
`author_name`	string	Name of the reviewer
`author_id`	string	Unique identifier for the reviewer
`rating`	integer	Review rating (1-5)
`text`	string	Review text content
`url`	string	URL to the original review
`posted_at`	integer	Unix timestamp when review was posted
`review_hash`	string	Unique hash for deduplication
`language`	string	Language code of the review

Pagination Object

Field	Type	Description
`total_reviews`	integer	Total number of reviews available
`page`	integer	Current page number
`page_size`	integer	Number of reviews per page
`total_pages`	integer	Total number of pages
`has_next`	boolean	Whether there are more pages
`has_previous`	boolean	Whether there are previous pages

Error Response Model

Schema

{
  "error": "string",
  "details": {
    "field_name": ["string"]
  }
}

Fields

Field	Type	Description
`error`	string	Error message description
`details`	object	Detailed validation errors

Example

{
  "error": "Invalid payload",
  "details": {
    "data": {
      "business": {
        "address": {
          "street": ["This field is required."]
        }
      }
    }
  }
}

Webhook Response Model

Schema

{
  "webhook": "string",
  "status": "string"
}

Fields

Field	Type	Description
`webhook`	string (URI)	Successfully configured webhook URL
`status`	string	Operation status (success/error)

Example

{
  "webhook": "https://example.com/webhook",
  "status": "success"
}

Response Examples

Completed Task with Reviews

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

Task In Progress

{
  "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
  "foreign_key": "TEST_1751004113518_i6yxcl",
  "publisher_key": "maps.google.com",
  "response_message": [
    {
      "status": "in_progress",
      "message": "Task is currently being processed",
      "task_status": 101
    }
  ]
}

Task Queued

{
  "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
  "foreign_key": "TEST_1751004113518_i6yxcl",
  "publisher_key": "maps.google.com",
  "response_message": [
    {
      "status": "queued",
      "message": "Task is queued and waiting to be processed",
      "task_status": 100
    }
  ]
}

Task Failed

{
  "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
  "foreign_key": "TEST_1751004113518_i6yxcl",
  "publisher_key": "maps.google.com",
  "response_message": [
    {
      "status": "failed",
      "message": "Task processing failed",
      "task_status": 500
    }
  ]
}

Status Codes

Task Status Codes

Code	Meaning	Description
`200`	OK	Task completed successfully
`400`	Bad Request	No business page found
`401`	Unauthorized	Authentication error
`404`	Not Found	Could not find Business
`422`	Unprocessable Entity	Invalid Payload
`429`	Too Many Requests	Rate limiting
`450`	Format Change	Change detected in page format
`451`	Encryption Error	Publisher encryption failure
`452`	Geoservice Error	Geoservice failure
`460`	No Reviews	Business has no reviews
`461`	No New Reviews	Business has no new reviews
`472`	Google Special Case	Special case failure for Google
`500`	Internal Server Error	Unknown error
`503`	Service Unavailable	Service unavailable
`504`	Gateway Timeout	Process timed out
`505`	Fatal Error	Fatal unrecoverable error
`530`	Partial Success	Some reviews present, but error occurred
`532`	Partial Success	Some reviews present, but hit max attempts

HTTP Status Codes

Code	Description
`200`	OK - Request successful
`201`	Created - Resource created successfully
`400`	Bad Request - Invalid request
`401`	Unauthorized - Authentication required
`404`	Not Found - Resource not found
`422`	Unprocessable Entity - Validation failed
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Server error

Best Practices

Response Handling

Status Code Checking: Always check both HTTP status codes and task status codes
Error Handling: Implement comprehensive error handling for all response types
Pagination: Handle pagination properly for large datasets
Base64 Decoding: Decode base64 encoded fields when displaying data

Data Processing

Review Deduplication: Use review hashes to prevent duplicates
Data Validation: Validate review data before processing
Language Detection: Use language codes for internationalization
Date Handling: Convert timestamps to appropriate timezone

Performance

Caching: Cache completed task results
Pagination: Use appropriate page sizes
Polling: Implement exponential backoff for incomplete tasks
Monitoring: Monitor response times and error rates

Business Model - Business information structure
Publisher Model - Publisher configuration structure
Request Payload Model - Request structure

Success Response Model​

Schema​

Fields​

Example​

Task Response Model​

Schema​

Fields​

Response Message Object​

Review Object​

Pagination Object​

Error Response Model​

Schema​

Fields​

Example​

Webhook Response Model​

Schema​

Fields​

Example​

Response Examples​

Completed Task with Reviews​

Task In Progress​

Task Queued​

Task Failed​

Status Codes​

Task Status Codes​

HTTP Status Codes​

Best Practices​

Response Handling​

Data Processing​

Performance​

Related Models​

Success Response Model

Schema

Fields

Example

Task Response Model

Schema

Fields

Response Message Object

Review Object

Pagination Object

Error Response Model

Schema

Fields

Example

Webhook Response Model

Schema

Fields

Example

Response Examples

Completed Task with Reviews

Task In Progress

Task Queued

Task Failed

Status Codes

Task Status Codes

HTTP Status Codes

Best Practices

Response Handling

Data Processing

Performance

Related Models