Skip to main content

Property Details

Documentation for GET /api/v1/public/properties endpoint.

curl 'https://staging.villra.com/api/v1/public/properties/78c7e562-12cb-44dc-ac61-5503b146e101'

Notes on the Randomized Fields

  1. title: Changed to a different property name.
  2. currency: Switched to USD vs. the original AED.
  3. email/phone: Generated a generic booking contact.
  4. zip_code/city/state: Swapped to Miami, FL, 33131.
  5. latitude/longitude: Correspond to downtown Miami coordinates.
  6. facilities: Added three example strings ("wifi", "parking", "pool_access")—these are illustrative; the real API may return specific facility IDs or names.
  7. photo: Two photo entries instead of one, each with a new random UUID, URL, and descriptions.
  8. hotel_policy: Populated with two policy objects (check_in and check_out), each having a policy_type and detail.
  9. payment_method: One method enabled (direct), the other disabled (property).

Overview​

Retrieve detailed information about a single property by its unique identifier. The endpoint returns various metadata about the property, including location, contact details, images, and payment options.

Endpoint​

GET /api/v1/public/properties/{property_id}

Response Structure​

The response is a JSON object containing the following fields:

  • title (string): Human-readable name of the property.

  • currency (string): Currency code used for any price-related fields (e.g., AED, USD).

  • email (string): Primary contact email for booking inquiries.

  • phone (string): Primary contact phone number (including country code).

  • zip_code (string): Postal code of the property.

  • city (string): City where the property is located.

  • state (string): State/Region/Province where the property is located.

  • address (string): Street-level address or neighborhood.

  • country (string): Two-letter ISO country code (e.g., AE, US).

  • latitude (string): Latitude coordinate in decimal degrees.

  • longitude (string): Longitude coordinate in decimal degrees.

  • facilities (array of strings): List of facility identifiers or names (if none are available, this will be an empty array).

  • photo (array of objects): List of photo objects, each containing:

    • id (string, UUID): Unique identifier for the image.
    • url (string): Direct link to the image file.
    • description (string or null): Alt-text or caption for the image (nullable).
    • position (integer): Order in which the image should be displayed (1-based index).

  • hotel_policy (array of objects): List of policy entries (e.g., check-in/check-out rules). If not applicable, this array will be empty.

  • payment_method (array of objects): Supported payment methods, each containing:

    • is_enabled (boolean): Indicates if that payment method is currently accepted.
    • method_type (string): Either "direct" or "property" to distinguish payment flows.

Field Descriptions​

Top-Level Fields​

  • title

    • Type: string
    • Example: "Cozy 2-Bed Townhouse near Downtown"
    • Description: A human-friendly name or title for the property listing.

  • currency

    • Type: string
    • Example: "USD"
    • Description: ISO 4217 currency code indicating which currency prices (if any) are displayed in.

  • email

    • Type: string
    • Example: "reservations@example-homes.com"
    • Description: Booking or inquiry email for this property.

  • phone

    • Type: string
    • Example: "+1-305-789-2145"
    • Description: Contact phone number (with country code).

  • zip_code

    • Type: string
    • Example: "33131"
    • Description: Postal code for the property’s location.

  • city / state / address

    • Type: string

    • Example:

      • "city": "Miami"
      • "state": "Florida"
      • "address": "1234 Biscayne Blvd, Unit 5"

    • Description: Detailed location information. city and state are separate fields; address can include street, unit number, or neighborhood.

  • country

    • Type: string
    • Example: "US"
    • Description: Two-letter ISO country code.

  • latitude / longitude

    • Type: string

    • Example:

      • "latitude": "25.7741728"
      • "longitude": "-80.19362"

    • Description: Geographic coordinates in decimal degrees. Stored as strings for precision.

  • facilities

    • Type: array of string
    • Example: ["wifi", "parking", "pool_access"]
    • Description: Array of facility identifiers or names applicable to this property. May be empty if no facilities are returned or tracked.

Nested Arrays​

photo (Array of Image Objects)​

Each object in the photo array represents one image of the property. Typical use is to iterate in ascending position order when displaying galleries.

  • id

    • Type: string (UUID)
    • Example: "b7f35c9a-9d1c-4a2b-b7e1-8f1a6a5d3f2b"
    • Description: Unique identifier of the image.

  • url

    • Type: string
    • Example: "https://cdn.example.com/images/5ae78f20-3c11-4c38-87f2-ea9b6d1b0f5d/"
    • Description: Publicly accessible link to the photo file. In practice, might be a CDN URL.

  • description

    • Type: string or null
    • Example: "Front view of the townhouse" or null
    • Description: Alt-text or caption. If no description is provided by the data source, this value will be null.

  • position

    • Type: integer
    • Example: 1 or 2
    • Description: Ordering index (1-based). Lower numbers indicate higher display priority.

hotel_policy (Array of Policy Objects)​

Represents rules or conditions that apply to bookings. If there are no specific policies, this array may be empty.

  • policy_type

    • Type: string
    • Example: "check_in", "check_out", "cancellation", "no_show", etc.
    • Description: Short code for the policy type.

  • detail

    • Type: string
    • Example: "Check-in after 3:00 PM"
    • Description: Human-readable explanation of that policy.

payment_method (Array of Payment Option Objects)​

Specifies whether certain payment flows are enabled for this property:

  • is_enabled

    • Type: boolean
    • Example: true or false
    • Description: true if this method is currently accepted, false otherwise.

  • method_type

    • Type: string

    • Allowed Values:

      • "direct": Payment is handled directly (e.g., through a payment gateway).
      • "property": Payment is handled on-site or through the property owner.

    • Example: "direct" or "property"

How to Consume This Endpoint​

  1. Construct the URL: Replace {property_id} in:

    https://staging.villra.com/api/v1/public/properties/{property_id}

    with the UUID of the property you wish to fetch.

  2. Send the GET Request: Use curl, Postman, or any HTTP library. Ensure you include Accept: application/json.

  3. Parse the JSON Payload:

    • Read top-level fields—title, currency, email, etc.—to display property metadata.
    • Iterate over photo array to render any property images in the correct order.
    • If hotel_policy is non-empty, show check-in/check-out or cancellation rules.
    • Display which payment methods are enabled based on the payment_method array.

  4. Example Workflow:

    • Show the property’s title, address, and city/state.
    • Render photo gallery using photo.url in ascending position.
    • Highlight any available facilities (e.g., Wi-Fi, parking).
    • Surface hotel_policy details under a “Hotel Policies” section.
    • Show checkboxes or icons for enabled payments (e.g., direct payment vs. on-site).

Quick Reference Table​

FieldTypeDescription
titlestringHuman-readable name of the property.
currencystringISO 4217 currency code (e.g., USD, AED).
emailstringBooking or inquiry email.
phonestringContact phone number (with country code).
zip_codestringPostal code for the property’s location.
city / state / addressstringDetailed location info (city, region, street).
countrystringTwo-letter ISO country code.
latitude / longitudestringGeographic coordinates (decimal degrees).
facilitiesarray[string]List of facility identifiers or names (may be empty).
photoarray[object]List of photo objects (each with id, url, description, position).
hotel_policyarray[object]List of property rules (e.g., check-in/out). May be empty.
payment_methodarray[object]Supported payment methods with is_enabled and method_type.