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
Field | Type | Required | Description |
---|---|---|---|
profile_key | string | Yes | Business URL/ID at publisher |
last_review_hashes | array | Yes | Hashes from previous reviews |
first_page_only | boolean | Yes | true = first page, false = all pages |
persona | object | No | Additional 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
- Google Maps:
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.
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
Cookie Object
{
"name": "string",
"value": "string",
"domain": "string"
}
Field | Type | Required | Description |
---|---|---|---|
name | string | Yes | Cookie name |
value | string | Yes | Cookie value |
domain | string | Yes | Cookie 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
- Invalid Profile Key: 400 Bad Request
- Authentication Required: 401 Unauthorized
- Rate Limiting: 429 Too Many Requests
- Business Not Found: 404 Not Found
Troubleshooting
- Verify profile key accuracy
- Check authentication credentials
- Monitor rate limits
- Validate cookie formats
Related Models
- Business Model - Business information
- Request Payload Model - Complete request structure
- Response Models - API response structures