Skip to main content

Publisher Model

The Publisher model defines the configuration for each review platform from which reviews will be collected.

Schema

{
"profile_key": "string",
"last_review_hashes": ["string"],
"first_page_only": "boolean",
"persona": {
"additional_cookies": {
"login": [
{
"name": "string",
"value": "string",
"domain": "string"
}
]
}
}
}

Fields

FieldTypeRequiredDescription
profile_keystringYesBusiness URL/ID at publisher
last_review_hashesarrayYesHashes from previous reviews
first_page_onlybooleanYestrue = first page, false = all pages
personaobjectNoAdditional configuration for specific publishers

Field Details

Profile Key

  • Type: string (URI format)
  • Required: Yes
  • Description: The URL or identifier for the business on the specific publisher platform
  • Examples:
    • Google Maps: https://www.google.com/maps/place/Business-Name/@lat,lng,17z/
    • Yelp: https://www.yelp.com/biz/business-name
    • TripAdvisor: https://www.tripadvisor.com/Restaurant_Review-g12345-d123456-Reviews-Business_Name-City_State.html
Important Request Limitations

Each API request can only target ONE review platform at a time.

This means:

  • Single request: Get reviews from Google Maps for McDonald's
  • NOT allowed: Get reviews from Google Maps + Yelp + TripAdvisor for McDonald's in one request

For multiple platforms, submit separate requests:

  • Request 1: McDonald's reviews from Google Maps
  • Request 2: McDonald's reviews from Yelp
  • Request 3: McDonald's reviews from TripAdvisor

Example: If you want review data from 5 different platforms (Google Maps, Yelp, TripAdvisor, Facebook, etc.) for the same business location, you must submit 5 separate API requests.

Profile Key Cost Information

What is a Profile Key? The profile_key is the direct URL to your business on a review platform (e.g., your Google Maps listing URL, Yelp business page URL).

Cost Impact:

  • 🟢 Provide the profile_key = Standard pricing (you pay only for review data extraction)
  • 🔴 Don't provide profile_key = Standard pricing + extra business search fee

How it works:

  • With profile_key: You give us the exact business URL → We extract reviews → You pay standard rate
  • Without profile_key: You give us business name/address → We find your business URL → We extract reviews → You pay standard rate + search fee

💰 Save Money: Always include the profile_key in your requests and save it for future use to avoid the additional search costs.

Last Review Hashes

  • Type: array of strings
  • Required: Yes
  • Description: Array of review hashes from previously collected reviews to prevent duplicates
  • Format: MD5 or SHA256 hashes
  • Examples: ["9487e4202954d101e15e95cc06a8c4e8", "6bb1a0e4195079f58506c60633cb20cc"]

First Page Only

  • Type: boolean
  • Required: Yes
  • Description: Controls whether to collect only the first page of reviews or all available pages
  • Values:
    • true: Collect only the first page (faster, fewer reviews)
    • false: Collect all available pages (slower, more comprehensive)

Persona Object

  • Type: object
  • Required: No
  • Description: Additional configuration for publishers that require authentication or special handling

Additional Cookies

  • Type: object
  • Description: Cookies required for accessing certain publishers (e.g., Facebook, Yelp)
  • Structure: Key-value pairs where keys are cookie categories
Login Cookies
  • Type: array of cookie objects
  • Description: Authentication cookies for logged-in access
  • Required for: Facebook, Yelp, and other platforms requiring authentication
{
"name": "string",
"value": "string",
"domain": "string"
}
FieldTypeRequiredDescription
namestringYesCookie name
valuestringYesCookie value
domainstringYesCookie domain

Examples

Basic Publisher Configuration

{
"profile_key": "https://www.google.com/maps/place/McDonald's/@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=EgoyMDI1MDYyMi4wIKXMDSoASAFQAw%3D%3D",
"last_review_hashes": [
"9487e4202954d101e15e95cc06a8c4e8",
"6bb1a0e4195079f58506c60633cb20cc"
],
"first_page_only": false
}

Publisher with Authentication

{
"profile_key": "https://www.yelp.com/biz/mcdonalds-new-york",
"last_review_hashes": [
"ceb5771ddd6ad12a036278263429de29",
"a034bbbbf6ea8e6995c3c409f996642d"
],
"first_page_only": false,
"persona": {
"additional_cookies": {
"login": [
{
"name": "session_id",
"value": "abc123def456",
"domain": ".yelp.com"
},
{
"name": "user_token",
"value": "xyz789uvw012",
"domain": ".yelp.com"
}
]
}
}
}

First Page Only Configuration

{
"profile_key": "https://www.tripadvisor.com/Restaurant_Review-g12345-d123456-Reviews-McDonald_s-New_York_City_New_York.html",
"last_review_hashes": [],
"first_page_only": true
}

Publisher-Specific Requirements

Google Maps (maps.google.com)

  • Profile Key: Full Google Maps business URL with coordinates
  • Special Features: Automatic geolocation support
  • Rate Limits: Standard limits apply
  • Authentication: Not required

Yelp (yelp.com)

  • Profile Key: Yelp business URL
  • Special Features: May require additional cookies for authentication
  • Rate Limits: Strict rate limiting, use with caution
  • Authentication: Often required for full access

Facebook (facebook.com)

  • Profile Key: Facebook business page URL
  • Special Features: Requires additional cookies for login
  • Rate Limits: Moderate rate limiting
  • Authentication: Required

TripAdvisor (tripadvisor.com)

  • Profile Key: TripAdvisor business page URL
  • Special Features: Multi-language support
  • Rate Limits: Standard limits apply
  • Authentication: Not required

Usage in API Requests

The Publisher model is used within the publishers object in the request payload:

{
"job": "App\\Jobs\\RequestReviews",
"data": {
"api_key": "your-api-key",
"foreign_key": "12345",
"lazy": true,
"business": {
// ... business data
},
"publishers": {
"maps.google.com": {
"profile_key": "https://www.google.com/maps/place/Business/@lat,lng,17z/",
"last_review_hashes": ["hash1", "hash2"],
"first_page_only": false
}
}
}
}

Best Practices

Profile Key

  • Accuracy: Ensure the profile key points to the correct business
  • Format: Use the exact URL format expected by each publisher
  • Verification: Test profile keys manually before submitting requests
  • Updates: Keep profile keys current as business URLs may change

Review Hashes

  • Storage: Maintain a database of collected review hashes
  • Updates: Update hashes after successful collection
  • Deduplication: Use hashes to prevent collecting duplicate reviews
  • Format: Use consistent hash algorithms across your system

First Page Only

  • Use Cases: Set to true for quick checks or limited data needs
  • Comprehensive: Set to false for complete review collection
  • Performance: Consider processing time and rate limits
  • Cost: May affect API usage and costs

Authentication

  • Security: Store authentication cookies securely
  • Rotation: Regularly update authentication credentials
  • Monitoring: Monitor for authentication failures
  • Fallback: Have backup authentication methods when possible

Validation Rules

Profile Key

  • Format: Valid URI
  • Length: 1-2000 characters
  • Protocol: HTTPS recommended
  • Domain: Must match publisher domain

Last Review Hashes

  • Format: Array of strings
  • Length: 0-1000 hashes
  • Hash Format: MD5 or SHA256
  • Uniqueness: Each hash should be unique

First Page Only

  • Type: Boolean
  • Default: false
  • Usage: Controls pagination behavior

Additional Cookies

  • Format: Valid cookie objects
  • Security: Sensitive data, handle with care
  • Expiration: Monitor cookie expiration
  • Validation: Verify cookie format and domain

Error Handling

Common Issues

  1. Invalid Profile Key: 400 Bad Request
  2. Authentication Required: 401 Unauthorized
  3. Rate Limiting: 429 Too Many Requests
  4. Business Not Found: 404 Not Found

Troubleshooting

  • Verify profile key accuracy
  • Check authentication credentials
  • Monitor rate limits
  • Validate cookie formats