Version 1

Version 1 introduces a comprehensive API schema overhaul, improved response quality and clarity, and new endpoints across our Partner API and Feed API. This changelog documents all API schema changes and breaking changes between v0 and v1.

Versioning

v1 is selected via a query parameter.

Pass ?version=BETA to receive v1 responses
Pass ?version=0 to receive v0 responses

Example: GET /locations/{id}?version=BETA

Breaking Changes Summary

Type Changes

Endpoint	Field Path	v0 Type	v1 Type
Locations Reviews	`review.id`	String	Long
Locations	`status.value`	String	Enum
Location Reviews	`review.id`	String	Long

Structure Changes

Endpoint	Change	Migration Action
Locations	`traveler_ratings.overall.subratings` → `traveler_ratings.subratings`	Update JSON parsing path
Locations	`traveler_ratings.overall.breakdowns` → `traveler_ratings.breakdowns`	Update JSON parsing path
Locations	`traveler_ratings.overall.language_counts` → `traveler_ratings.language_counts`	Update JSON parsing path
Location Reviews	Same subrating restructuring as Locations	Update JSON parsing path

Removed Fields

No fields have been removed. All v0 fields are available in v1 (though some have moved location in the response structure).

API Changes

Locations Endpoints

Add ?version=BETA to receive v1 responses.

Location Object Schema Changes

Changed: Status Object

v0 Structure:

{
  "status": {
    "value": "OPEN",           // String
    "closed_date": "2025-01-01",
    "reopen_date": "2025-06-01"
  }
}

v1 Structure:

{
  "status": {
    "value": "OPEN",           // Enum: "OPEN" | "CLOSED" | "TEMPORARILY_CLOSED"
    "closed_date": "2025-01-01",
    "reopen_date": "2025-06-01"
  }
}

Breaking Change: The value field is now an enum instead of a free-form string.

Changed: Traveler Ratings Object

v0 Structure:

{
  "traveler_ratings": {
    "overall": {
      "rating": 4.5,
      "count": 1234,
      "icon_url": "https://...",
      "subratings": [...],
      "breakdowns": [...],
      "language_counts": [...]
    }
  }
}

v1 Structure:

{
  "traveler_ratings": {
    "overall": {
      "rating": 4.5,
      "count": 1234,
      "icon_url": "https://..."
    },
    "subratings": [...],
    "breakdowns": [...],
    "language_counts": [...]
  }
}

Breaking Change: subratings, breakdowns, and language_counts arrays have been moved from nested inside overall to the top level of traveler_ratings.

Enhanced: Subratings

v0 Subrating Object:

{
  "type": "service",
  "rating": 4.5,
  "count": 500
}

v1 Subrating Object:

{
  "type": "service",
  "rating": 4.5,
  "count": 500,
  "icon_url": "https://...",    // NEW
  "type_name": "Service"         // NEW
}

New Fields:

icon_url (String): URL to icon representing the subrating category
type_name (String): Human-readable name for the subrating type

Location Reviews Endpoints

Add ?version=BETA to receive v1 responses.

LocationReviews Object Schema Changes

Changed: Review ID Type

v0:

{
  "id": "12345"  // String
}

v1:

{
  "id": 12345    // Long (numeric)
}

Breaking Change: Review id field changed from String to Long.

Changed: Rating Icon URL

v0:

{
  "rating_icon_url": null  // Can be null or omitted
}

v1:

{
  "rating_icon_url": "https://..."  // Always present when rating exists
}

Enhancement: The rating_icon_url field is now consistently populated.

Enhanced: Review Subratings

v0 Review Subrating:

{
  "type": "service",
  "rating": 5
}

v1 Review Subrating:

{
  "type": "service",
  "rating": 5,
  "icon_url": {               // NEW - ImageUrl object
    "url": "https://...",
    "width": 24,
    "height": 24
  },
  "type_name": "Service"      // NEW
}

New Fields:

icon_url (ImageUrl object): Icon URL with dimensions
type_name (String): Human-readable name for the subrating type

Changed: Traveler Ratings Structure

Same restructuring as in Location object - subratings moved to top level:

v0:

{
  "traveler_ratings": {
    "overall": {
      "rating": 4.5,
      "count": 1234,
      "icon_url": {...},
      "subratings": [...]
    }
  }
}

v1:

{
  "traveler_ratings": {
    "overall": {
      "rating": 4.5,
      "count": 1234,
      "icon_url": {...}
    },
    "subratings": [...]
  }
}

Recommendations Search Endpoint

Add ?version=BETA to receive v1 responses. Same changes applied to Location object described above.

Migration Notes

Add ?version=BETA to requests to receive v1 responses (use ?version=0 for v0)
Update parsing for moved traveler ratings fields
Treat review id as a number (Long)
Handle status value as an enum (OPEN, CLOSED, TEMPORARILY_CLOSED)
Expect omitted empty/null fields instead of empty objects

Support

For questions or issues with migration:

Refer to the complete API documentation
Test in development environment before production deployment
Contact API support for migration assistance

Last Updated: October 31, 2025
Version: 1.0.0