@vepler/sdk 3.3.0 → 6.0.0

package/src/sdk/models/operations/querylistings.ts

@@ -14,19 +14,19 @@ import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 /**
- * Sort direction. 'asc': ascending (lowest/oldest first). 'desc': descending (highest/newest first). Defaults to 'desc'.
+ * Sort direction. This endpoint always returns the most recently published listing first, so the value has no effect.
  */
 export const Order = {
   Asc: "asc",
   Desc: "desc",
 } as const;
 /**
- * Sort direction. 'asc': ascending (lowest/oldest first). 'desc': descending (highest/newest first). Defaults to 'desc'.
+ * Sort direction. This endpoint always returns the most recently published listing first, so the value has no effect.
  */
 export type Order = ClosedEnum<typeof Order>;
 
 /**
- * Field to sort results by. 'publishedDate': sort by when the listing first appeared on the portal. 'price': sort by current asking price or rent. 'updatedAt': sort by most recent modification. If omitted, results are returned in default relevance order.
+ * Field to sort by. This endpoint always sorts by publication date, so the value has no effect; `POST /listings/query/advanced` offers a choice of sort fields.
  */
 export const OrderBy = {
   PublishedDate: "publishedDate",
@@ -34,12 +34,12 @@ export const OrderBy = {
   UpdatedAt: "updatedAt",
 } as const;
 /**
- * Field to sort results by. 'publishedDate': sort by when the listing first appeared on the portal. 'price': sort by current asking price or rent. 'updatedAt': sort by most recent modification. If omitted, results are returned in default relevance order.
+ * Field to sort by. This endpoint always sorts by publication date, so the value has no effect; `POST /listings/query/advanced` offers a choice of sort fields.
  */
 export type OrderBy = ClosedEnum<typeof OrderBy>;
 
 /**
- * Filter listings to only those with the specified status. If omitted, listings of all statuses are returned.
+ * Return only listings with this status. Omit it to return listings of every status.
  */
 export const Status = {
   Live: "live",
@@ -47,150 +47,150 @@ export const Status = {
   Removed: "removed",
 } as const;
 /**
- * Filter listings to only those with the specified status. If omitted, listings of all statuses are returned.
+ * Return only listings with this status. Omit it to return listings of every status.
  */
 export type Status = ClosedEnum<typeof Status>;
 
 /**
- * Query parameters for searching and filtering property listings. Supports location-based, provider-based, and status-based filtering with pagination and sorting.
+ * Filters for a listing search. Only `status` and `limit` change the result: the endpoint returns the most recently published listings, newest first.
  */
 export type QueryListingsRequestBody = {
   /**
-   * Maximum number of listings to return per page. Must be between 1 and 100. Defaults to 25.
+   * Maximum number of listings to return. Defaults to 25. Minimum 1, maximum 100.
    */
   limit?: number | undefined;
   /**
-   * Filter listings by one or more location IDs (postcode with spaces removed, e.g. 'SW1A1AA'). When multiple IDs are provided, listings matching any of the locations are returned (OR logic).
+   * Location IDs to match. This endpoint does not apply the filter; to search by location, use `POST /listings/query/advanced` with a `locationId` condition.
    */
   locationIds?: Array<string> | undefined;
   /**
-   * Number of listings to skip for pagination. Use in combination with 'limit' to page through results. Defaults to 0 (start from the beginning).
+   * Number of results to skip before the first one returned. Defaults to 0. This endpoint does not page, so results always start with the most recently published listing.
    */
   offset?: number | undefined;
   /**
-   * Sort direction. 'asc': ascending (lowest/oldest first). 'desc': descending (highest/newest first). Defaults to 'desc'.
+   * Sort direction. This endpoint always returns the most recently published listing first, so the value has no effect.
    */
   order?: Order | undefined;
   /**
-   * Field to sort results by. 'publishedDate': sort by when the listing first appeared on the portal. 'price': sort by current asking price or rent. 'updatedAt': sort by most recent modification. If omitted, results are returned in default relevance order.
+   * Field to sort by. This endpoint always sorts by publication date, so the value has no effect; `POST /listings/query/advanced` offers a choice of sort fields.
    */
   orderBy?: OrderBy | undefined;
   /**
-   * Filter listings by one or more data provider identifiers. When multiple providers are specified, listings from any of the providers are returned (OR logic).
+   * Data provider identifiers to match. This endpoint does not apply the filter; to search by provider, use `POST /listings/query/advanced` with a `provider` condition.
    */
   providers?: Array<string> | undefined;
   /**
-   * Filter listings to only those with the specified status. If omitted, listings of all statuses are returned.
+   * Return only listings with this status. Omit it to return listings of every status.
    */
   status?: Status | undefined;
 };
 
 /**
- * Structured postal address for the listed property. Fields are parsed from the original listing data and may be incomplete depending on what the agent provided. The postcode is always present and serves as the primary geographic key.
+ * Postal address of the listed property, parsed into its parts. A part is absent when the source did not supply it; the postcode is always present.
  */
 export type QueryListingsAddress = {
   /**
-   * City, town, or village name as used by Royal Mail for postal addressing.
+   * Town, city or village used in the postal address.
    */
   city?: string | null | undefined;
   /**
-   * ISO 3166-1 alpha-2 country code. Defaults to 'GB' for Great Britain. Currently only UK properties are supported.
+   * Country the property is in, as an ISO 3166-1 alpha-2 code. Defaults to `GB`.
    */
   country: string;
   /**
-   * Local district, borough, or neighbourhood within the city (e.g. 'Westminster', 'Shoreditch', 'Didsbury').
+   * District, borough or neighbourhood within the town or city.
    */
   district?: string | null | undefined;
   /**
-   * Inward code — the second part of the UK postcode after the space (e.g. '1AA', '4QE'). Combined with outcode forms the full postcode.
+   * The part of the postcode after the space, such as `1AA`. With the outward code it forms the full postcode.
    */
   incode?: string | null | undefined;
   /**
-   * The raw, unstructured address string exactly as received from the source data feed, before any parsing or normalisation. Useful for display purposes or debugging address-matching issues.
+   * The address exactly as the source supplied it, before it was parsed into the fields above.
    */
   originalAddress: string;
   /**
-   * Outward code — the first part of the UK postcode before the space (e.g. 'SW1A', 'M1', 'EC2'). Useful for area-level grouping and search.
+   * The postcode's outward code (the first part, such as `SW1A`), which groups a wider area.
    */
   outcode?: string | null | undefined;
   /**
-   * Full UK postcode in standard Royal Mail format (e.g. 'SW1A 1AA'). Always present and is the primary geographic identifier used for location matching.
+   * Full UK postcode for the property, such as `SW1A 1AA`.
    */
   postcode: string;
   /**
-   * Building or house number, including any suffix (e.g. '12A', '3-5'). May be absent for named properties or new-build plots.
+   * Building number for the property, including any suffix such as '12A' or a range such as '3-5'.
    */
   propertyNumber?: string | null | undefined;
   /**
-   * County or administrative region (e.g. 'Greater London', 'West Yorkshire', 'Surrey').
+   * County or wider administrative area the property sits in.
    */
   region?: string | null | undefined;
   /**
-   * Street or road name, without the property number. May include thoroughfare type (e.g. 'High Street', 'Park Lane', 'The Crescent').
+   * Name of the street the property sits on, without the building number.
    */
   street?: string | null | undefined;
 };
 
 /**
- * Contact and identification details for the estate agent marketing this property. All agent data is publicly available information sourced from property portal listings. Null if agent details were not available in the source feed.
+ * The agent marketing this property. Null when the source supplied no agent details.
  */
 export type QueryListingsAgent = {
   /**
-   * Postal address of the estate agency branch office, as a single formatted string.
+   * Postal address of the branch office, as a single formatted string.
    */
   address?: string | undefined;
   /**
-   * Opaque identifier for the agency within the source provider's system. Can be used to group listings across all branches of the same agency.
+   * Identifier for the agency in the source provider's system, which can be used to group listings across all of its branches.
    */
   agencyId?: string | undefined;
   /**
-   * Trading name of the parent estate agency company (e.g. 'Savills', 'Foxtons', 'Purplebricks'). This is the top-level brand that owns one or more branches.
+   * Trading name of the agency the branch belongs to.
    */
   agencyName?: string | undefined;
   /**
-   * Opaque identifier for the individual agent within the source provider's system. Format varies by provider.
+   * Identifier for the individual agent in the source provider's system. Its format varies by provider.
    */
   agentId?: string | undefined;
   /**
-   * Name of the individual estate agent or negotiator handling this listing. This is publicly available information from property portals.
+   * Name of the individual agent or negotiator handling this listing.
    */
   agentName?: string | undefined;
   /**
-   * Opaque identifier for the branch within the source provider's system. Can be used to group listings by branch.
+   * Identifier for the branch in the source provider's system, which can be used to group listings by branch.
    */
   branchId?: string | undefined;
   /**
-   * Name of the specific estate agency branch marketing this property (e.g. 'Kensington Office', 'Manchester City Centre'). A single agency may have multiple branches.
+   * Name of the branch marketing this property. An agency may run several branches.
    */
   branchName?: string | undefined;
   /**
-   * Primary contact email address for the branch. This is publicly listed contact information from property portals.
+   * Main contact email address for the branch.
    */
   email?: string | undefined;
   /**
-   * Additional email addresses for the branch or individual agents. These are publicly available from property portal listings.
+   * Any further email addresses held for the branch or its agents.
    */
   emails?: Array<string> | undefined;
   /**
-   * Primary contact telephone number for the branch, typically a UK landline or local rate number. This is publicly listed contact information from property portals. Format varies (e.g. '020 1234 5678', '02012345678').
+   * Main contact telephone number for the branch. Formatting varies between sources.
    */
   phone?: string | undefined;
   /**
-   * Additional contact telephone numbers for the branch (e.g. mobile numbers, out-of-hours lines). These are publicly available from property portal listings.
+   * Any further telephone numbers held for the branch.
    */
   phones?: Array<string> | undefined;
   /**
-   * UK postcode of the estate agency branch office.
+   * Postcode of the branch office.
    */
   postcode?: string | undefined;
   /**
-   * URL of the agency's website. May point to the branch-specific page or the agency homepage.
+   * URL of the agency's website. It may point at the branch page or the agency home page.
    */
   website?: string | undefined;
 };
 
 /**
- * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
+ * What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.
  */
 export const QueryListingsListingsType = {
   Standard: "standard",
@@ -199,48 +199,48 @@ export const QueryListingsListingsType = {
   Brochure: "brochure",
 } as const;
 /**
- * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
+ * What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.
  */
 export type QueryListingsListingsType = OpenEnum<
   typeof QueryListingsListingsType
 >;
 
 /**
- * A single image asset associated with a property listing. Images are sourced from property portal CDNs and are publicly accessible.
+ * One image belonging to a property listing.
  */
 export type QueryListingsBrochureImages = {
   /**
-   * Human-readable caption describing the image content, as provided by the listing agent (e.g. 'Master bedroom', 'Rear garden', 'Kitchen/diner').
+   * Caption describing what the image shows, as supplied with the listing.
    */
   caption?: string | null | undefined;
   /**
-   * Zero-based display order for the image within its type group. The first image (order 0) is typically the hero/primary image used for thumbnails and search results.
+   * Position of the image within its type group, counting from 0. The lowest number is the primary image.
    */
   order?: number | undefined;
   /**
-   * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
+   * What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.
    */
   type?: QueryListingsListingsType | undefined;
   /**
-   * Absolute URL to the image file. URLs may include query parameters for resizing.
+   * Absolute URL of the image file.
    */
   url: string;
 };
 
 /**
- * Broad property category. 'residential': dwellings including houses, flats, bungalows, and maisonettes. 'commercial': non-residential premises such as offices, retail units, warehouses, and mixed-use buildings.
+ * Broad category the property falls into: a residential dwelling, or commercial premises such as offices, retail units, warehouses and industrial space.
  */
 export const QueryListingsCategory = {
   Residential: "residential",
   Commercial: "commercial",
 } as const;
 /**
- * Broad property category. 'residential': dwellings including houses, flats, bungalows, and maisonettes. 'commercial': non-residential premises such as offices, retail units, warehouses, and mixed-use buildings.
+ * Broad category the property falls into: a residential dwelling, or commercial premises such as offices, retail units, warehouses and industrial space.
  */
 export type QueryListingsCategory = OpenEnum<typeof QueryListingsCategory>;
 
 /**
- * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
+ * What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.
  */
 export const QueryListingsListingsResponseType = {
   Standard: "standard",
@@ -249,50 +249,50 @@ export const QueryListingsListingsResponseType = {
   Brochure: "brochure",
 } as const;
 /**
- * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
+ * What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.
  */
 export type QueryListingsListingsResponseType = OpenEnum<
   typeof QueryListingsListingsResponseType
 >;
 
 /**
- * A single image asset associated with a property listing. Images are sourced from property portal CDNs and are publicly accessible.
+ * One image belonging to a property listing.
  */
 export type QueryListingsEnergyRatingImages = {
   /**
-   * Human-readable caption describing the image content, as provided by the listing agent (e.g. 'Master bedroom', 'Rear garden', 'Kitchen/diner').
+   * Caption describing what the image shows, as supplied with the listing.
    */
   caption?: string | null | undefined;
   /**
-   * Zero-based display order for the image within its type group. The first image (order 0) is typically the hero/primary image used for thumbnails and search results.
+   * Position of the image within its type group, counting from 0. The lowest number is the primary image.
    */
   order?: number | undefined;
   /**
-   * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
+   * What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.
    */
   type?: QueryListingsListingsResponseType | undefined;
   /**
-   * Absolute URL to the image file. URLs may include query parameters for resizing.
+   * Absolute URL of the image file.
    */
   url: string;
 };
 
 /**
- * A structured key-value property feature extracted from the listing. Features capture specific property attributes such as tenure, EPC rating, parking arrangements, and amenities.
+ * One property feature stated in the listing, as a key and the value given for it.
  */
 export type QueryListingsFeatures = {
   /**
-   * Normalised feature identifier key. Common values include: 'parking', 'garden', 'garage', 'central_heating', 'double_glazing', 'epc_rating', 'council_tax_band', 'tenure', 'chain_free', 'conservatory', 'fireplace'. The set of available feature IDs varies by data provider and is not strictly enumerated — treat as a free-form key.
+   * Key naming the feature, for example 'TENURE', 'FLOORS' or 'FLOOR_AREA'. Feature keys are an open set that varies by data provider, so treat this as free-form rather than a fixed list.
    */
   featureId: string;
   /**
-   * Human-readable feature value as stated by the agent. For boolean-style features this may be 'Yes'/'No'; for categorical features it contains the specific value (e.g. 'Band D' for council_tax_band, 'C' for epc_rating, 'Freehold' for tenure).
+   * The value stated for the feature, as supplied with the listing. It may be a yes or no answer, a measurement, or a category such as 'Freehold'.
    */
   value: string;
 };
 
 /**
- * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
+ * What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.
  */
 export const QueryListingsListingsResponse200Type = {
   Standard: "standard",
@@ -301,36 +301,36 @@ export const QueryListingsListingsResponse200Type = {
   Brochure: "brochure",
 } as const;
 /**
- * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
+ * What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.
  */
 export type QueryListingsListingsResponse200Type = OpenEnum<
   typeof QueryListingsListingsResponse200Type
 >;
 
 /**
- * A single image asset associated with a property listing. Images are sourced from property portal CDNs and are publicly accessible.
+ * One image belonging to a property listing.
  */
 export type QueryListingsFloorPlanImages = {
   /**
-   * Human-readable caption describing the image content, as provided by the listing agent (e.g. 'Master bedroom', 'Rear garden', 'Kitchen/diner').
+   * Caption describing what the image shows, as supplied with the listing.
    */
   caption?: string | null | undefined;
   /**
-   * Zero-based display order for the image within its type group. The first image (order 0) is typically the hero/primary image used for thumbnails and search results.
+   * Position of the image within its type group, counting from 0. The lowest number is the primary image.
    */
   order?: number | undefined;
   /**
-   * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
+   * What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.
    */
   type?: QueryListingsListingsResponse200Type | undefined;
   /**
-   * Absolute URL to the image file. URLs may include query parameters for resizing.
+   * Absolute URL of the image file.
    */
   url: string;
 };
 
 /**
- * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
+ * What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.
  */
 export const QueryListingsListingsResponse200ApplicationJSONType = {
   Standard: "standard",
@@ -339,41 +339,41 @@ export const QueryListingsListingsResponse200ApplicationJSONType = {
   Brochure: "brochure",
 } as const;
 /**
- * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
+ * What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.
  */
 export type QueryListingsListingsResponse200ApplicationJSONType = OpenEnum<
   typeof QueryListingsListingsResponse200ApplicationJSONType
 >;
 
 /**
- * A single image asset associated with a property listing. Images are sourced from property portal CDNs and are publicly accessible.
+ * One image belonging to a property listing.
  */
 export type QueryListingsImages = {
   /**
-   * Human-readable caption describing the image content, as provided by the listing agent (e.g. 'Master bedroom', 'Rear garden', 'Kitchen/diner').
+   * Caption describing what the image shows, as supplied with the listing.
    */
   caption?: string | null | undefined;
   /**
-   * Zero-based display order for the image within its type group. The first image (order 0) is typically the hero/primary image used for thumbnails and search results.
+   * Position of the image within its type group, counting from 0. The lowest number is the primary image.
    */
   order?: number | undefined;
   /**
-   * Classification of the image asset. 'standard': property photography (exterior, rooms, garden, etc.). 'floorplan': annotated floor plan diagram with room dimensions. 'epc': Energy Performance Certificate chart or graph image. 'brochure': marketing brochure page scan or PDF-derived image.
+   * What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.
    */
   type?: QueryListingsListingsResponse200ApplicationJSONType | undefined;
   /**
-   * Absolute URL to the image file. URLs may include query parameters for resizing.
+   * Absolute URL of the image file.
    */
   url: string;
 };
 
 /**
- * The narrative text body. When a string: a single block of prose (may contain HTML line breaks or plain text). When an array: an ordered list of paragraphs or bullet points, each element being one distinct point. Null if the narrative section exists in the source feed but its content was empty or could not be extracted.
+ * The text itself. A string holds one block of prose; an array holds an ordered list of paragraphs or bullet points, one per element. Null when the block carries no text.
  */
 export type QueryListingsContent = string | Array<string>;
 
 /**
- * Type of narrative content. summary: brief overview of the property (1-2 sentences). description: full marketing description. features: bullet-pointed key selling points. location: description of the surrounding area, transport links, and amenities. other: additional narrative that does not fit other categories.
+ * What this block of marketing text covers: a short overview, the full description, the list of key features, the surrounding area, or anything that fits none of those.
  */
 export const QueryListingsListingsResponse200ApplicationJSONResponseBodyType = {
   Summary: "summary",
@@ -383,7 +383,7 @@ export const QueryListingsListingsResponse200ApplicationJSONResponseBodyType = {
   Other: "other",
 } as const;
 /**
- * Type of narrative content. summary: brief overview of the property (1-2 sentences). description: full marketing description. features: bullet-pointed key selling points. location: description of the surrounding area, transport links, and amenities. other: additional narrative that does not fit other categories.
+ * What this block of marketing text covers: a short overview, the full description, the list of key features, the surrounding area, or anything that fits none of those.
  */
 export type QueryListingsListingsResponse200ApplicationJSONResponseBodyType =
   OpenEnum<
@@ -391,21 +391,21 @@ export type QueryListingsListingsResponse200ApplicationJSONResponseBodyType =
   >;
 
 /**
- * A block of descriptive marketing copy associated with the listing. Narratives are authored by estate agents and extracted from property portal feeds. Content may contain marketing language and should not be treated as verified fact.
+ * A block of marketing copy supplied with the listing. It is written to sell the property, so treat it as the agent's description rather than verified fact.
  */
 export type QueryListingsNarratives = {
   /**
-   * The narrative text body. When a string: a single block of prose (may contain HTML line breaks or plain text). When an array: an ordered list of paragraphs or bullet points, each element being one distinct point. Null if the narrative section exists in the source feed but its content was empty or could not be extracted.
+   * The text itself. A string holds one block of prose; an array holds an ordered list of paragraphs or bullet points, one per element. Null when the block carries no text.
    */
   content: string | Array<string> | null;
   /**
-   * Type of narrative content. summary: brief overview of the property (1-2 sentences). description: full marketing description. features: bullet-pointed key selling points. location: description of the surrounding area, transport links, and amenities. other: additional narrative that does not fit other categories.
+   * What this block of marketing text covers: a short overview, the full description, the list of key features, the surrounding area, or anything that fits none of those.
    */
   type: QueryListingsListingsResponse200ApplicationJSONResponseBodyType;
 };
 
 /**
- * Direction of a price revision. 'increase': the asking price or rent was raised. 'decrease': the asking price or rent was reduced (commonly signals motivated seller or market correction). 'nochange': a price event was recorded but the value remained unchanged (e.g. relisting at the same price).
+ * Whether the price went up, went down, or stayed the same at this revision.
  */
 export const QueryListingsDirection = {
   Increase: "increase",
@@ -413,49 +413,49 @@ export const QueryListingsDirection = {
   Nochange: "nochange",
 } as const;
 /**
- * Direction of a price revision. 'increase': the asking price or rent was raised. 'decrease': the asking price or rent was reduced (commonly signals motivated seller or market correction). 'nochange': a price event was recorded but the value remained unchanged (e.g. relisting at the same price).
+ * Whether the price went up, went down, or stayed the same at this revision.
  */
 export type QueryListingsDirection = OpenEnum<typeof QueryListingsDirection>;
 
 /**
- * A single price revision event in the listing's history. Price changes are tracked chronologically and can be used to analyse market trends, seller motivation, and time-on-market patterns. All monetary values are in GBP pence.
+ * One price revision recorded against the listing, with the size of the change in pounds.
  */
 export type QueryListingsPriceHistory = {
   /**
-   * Absolute price change in GBP pence (new price minus old price). Negative values indicate a price reduction; positive values indicate an increase.
+   * The new price minus the old one, in pounds, rounded to two decimal places. Negative when the price was cut.
    */
   amount?: number | undefined;
   /**
-   * ISO 8601 date when the price change was observed or published on the portal.
+   * When the price change was recorded, as an ISO 8601 timestamp.
    */
   date: Date;
   /**
-   * Direction of a price revision. 'increase': the asking price or rent was raised. 'decrease': the asking price or rent was reduced (commonly signals motivated seller or market correction). 'nochange': a price event was recorded but the value remained unchanged (e.g. relisting at the same price).
+   * Whether the price went up, went down, or stayed the same at this revision.
    */
   direction?: QueryListingsDirection | undefined;
   /**
-   * The previous listing price before the change, in GBP pence. Divide by 100 to convert to pounds sterling. May be absent for the initial listing event.
+   * The price before the change, in pounds. Not present for the first price recorded for a listing.
    */
   oldPrice?: number | undefined;
   /**
-   * Price change expressed as a percentage of the old price. Negative values indicate a reduction (e.g. -3.85 means a 3.85% reduction). Positive values indicate an increase.
+   * The change as a percentage of the previous price, rounded to two decimal places. Negative when the price was cut, so -3.85 is a cut of 3.85 per cent.
    */
   percent?: number | undefined;
   /**
-   * The new listing price after the change, in GBP pence. Divide by 100 to convert to pounds sterling. For sales listings this is the revised asking price; for rental listings this is the revised monthly rent (per calendar month).
+   * The price after the change, in pounds: the revised asking price for a sale listing, or the revised rent for a rental.
    */
   price: number;
 };
 
 /**
- * GeoJSON geometry type
+ * Geometry type discriminator. Always `Point`.
  */
 export const QueryListingsListingsResponse200ApplicationJSONResponseBodyDataType =
   {
     Point: "Point",
   } as const;
 /**
- * GeoJSON geometry type
+ * Geometry type discriminator. Always `Point`.
  */
 export type QueryListingsListingsResponse200ApplicationJSONResponseBodyDataType =
   ClosedEnum<
@@ -463,21 +463,21 @@ export type QueryListingsListingsResponse200ApplicationJSONResponseBodyDataType
   >;
 
 /**
- * GeoJSON Point geometry representing the property's geographic location. Coordinates are in WGS84 (EPSG:4326) as [longitude, latitude]. May be null if the property could not be geocoded. Accuracy varies — some coordinates represent postcode centroids rather than exact property positions.
+ * Where the property sits, as a GeoJSON Point. Null when the listing carries no coordinates.
  */
 export type QueryListingsGeoJSONPoint = {
   /**
-   * Coordinate pair [longitude, latitude]
+   * A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).
    */
   coordinates: Array<number>;
   /**
-   * GeoJSON geometry type
+   * Geometry type discriminator. Always `Point`.
    */
   type: QueryListingsListingsResponse200ApplicationJSONResponseBodyDataType;
 };
 
 /**
- * Current status of the listing. 'live': actively marketed on one or more property portals. 'archived': listing was taken off market by the agent but retained for historical analysis (e.g. price comparisons). 'removed': listing has been permanently withdrawn or the source feed no longer includes it. Typical lifecycle: live -> archived -> removed.
+ * Where the listing stands in its marketing life. 'live': currently being marketed. 'removed': withdrawn, or no longer present in the source feed.
  */
 export const QueryListingsStatus = {
   Live: "live",
@@ -485,202 +485,202 @@ export const QueryListingsStatus = {
   Removed: "removed",
 } as const;
 /**
- * Current status of the listing. 'live': actively marketed on one or more property portals. 'archived': listing was taken off market by the agent but retained for historical analysis (e.g. price comparisons). 'removed': listing has been permanently withdrawn or the source feed no longer includes it. Typical lifecycle: live -> archived -> removed.
+ * Where the listing stands in its marketing life. 'live': currently being marketed. 'removed': withdrawn, or no longer present in the source feed.
  */
 export type QueryListingsStatus = OpenEnum<typeof QueryListingsStatus>;
 
 /**
- * Market type for the listing. 'sale': property is listed for purchase — the price field represents the asking price in GBP pence. 'rent': property is listed for tenancy — the price field represents the monthly rental amount in GBP pence (per calendar month).
+ * Whether the property is advertised for sale or to rent. This governs how to read the price: an asking price for 'sale', the rent quoted by the source for 'rent'.
  */
 export const QueryListingsType = {
   Sale: "sale",
   Rent: "rent",
 } as const;
 /**
- * Market type for the listing. 'sale': property is listed for purchase — the price field represents the asking price in GBP pence. 'rent': property is listed for tenancy — the price field represents the monthly rental amount in GBP pence (per calendar month).
+ * Whether the property is advertised for sale or to rent. This governs how to read the price: an asking price for 'sale', the rent quoted by the source for 'rent'.
  */
 export type QueryListingsType = OpenEnum<typeof QueryListingsType>;
 
 /**
- * A property listing representing a single residential or commercial property advertised for sale or rent on a UK property portal. Listings are sourced from multiple data providers and may be aggregated to combine information from different feeds for the same physical property. All prices are in GBP pence.
+ * A single UK residential or commercial property advertised for sale or to rent. Listings come from several data providers, and an aggregated listing pulls together everything held for the property. Prices are in pounds.
  */
 export type QueryListingsData = {
   /**
-   * Structured postal address for the listed property. Fields are parsed from the original listing data and may be incomplete depending on what the agent provided. The postcode is always present and serves as the primary geographic key.
+   * Postal address of the listed property, parsed into its parts. A part is absent when the source did not supply it; the postcode is always present.
    */
   address: QueryListingsAddress;
   /**
-   * Contact and identification details for the estate agent marketing this property. All agent data is publicly available information sourced from property portal listings. Null if agent details were not available in the source feed.
+   * The agent marketing this property. Null when the source supplied no agent details.
    */
   agent?: QueryListingsAgent | null | undefined;
   /**
-   * Number of bathrooms as advertised by the agent, including en-suites and shower rooms. Null if not specified in the listing.
+   * Number of bathrooms advertised. Null when the listing does not state one.
    */
   baths?: number | null | undefined;
   /**
-   * Number of bedrooms as advertised by the agent. Null if the listing does not specify bedroom count (common for studios or commercial properties). A value of 0 typically indicates a studio flat.
+   * Number of bedrooms advertised. Null when the listing does not state one.
    */
   beds?: number | null | undefined;
   /**
-   * Marketing brochure images, typically scanned pages or PDF-derived images from the agent's printed particulars. Empty array if no brochure material is available.
+   * Images taken from the marketing brochure. Empty when there are none. Returned only to API keys entitled to listing media.
    */
   brochureImages?: Array<QueryListingsBrochureImages> | undefined;
   /**
-   * Broad property category. 'residential': dwellings including houses, flats, bungalows, and maisonettes. 'commercial': non-residential premises such as offices, retail units, warehouses, and mixed-use buildings.
+   * Broad category the property falls into: a residential dwelling, or commercial premises such as offices, retail units, warehouses and industrial space.
    */
   category?: QueryListingsCategory | null | undefined;
   /**
-   * ISO 8601 datetime when this listing record was first created in our system. This may differ from publishedDate if the listing was retrospectively imported.
+   * When this listing first appeared in the API, as an ISO 8601 timestamp. It differs from `publishedDate` when a listing is imported after the event.
    */
   createdAt?: Date | undefined;
   /**
-   * ISO 4217 currency code for all monetary values in this listing. Currently always 'GBP' (British Pound Sterling). All price fields are denominated in the smallest currency unit (pence).
+   * ISO 4217 currency code for the monetary values in this listing. Defaults to `GBP`.
    */
   currency: string;
   /**
-   * Pre-formatted address string suitable for display in search results and listing cards. This is the agent's preferred public-facing address and may be intentionally vague (e.g. omitting house number for privacy). Use the structured 'address' object for programmatic access.
+   * The address as the listing presents it, ready to show in search results and listing cards. Use `address` for the parsed parts.
    */
   displayAddress?: string | undefined;
   /**
-   * Energy Performance Certificate (EPC) chart images. In England and Wales, an EPC is legally required when a property is marketed for sale or rent. Typically contains one image showing the energy efficiency rating (A-G scale). Empty array if no EPC image is available.
+   * Energy Performance Certificate chart images. Empty when there are none. Returned only to API keys entitled to listing media.
    */
   energyRatingImages?: Array<QueryListingsEnergyRatingImages> | undefined;
   /**
-   * Structured key-value property features extracted from the listing (e.g. tenure, EPC rating, council tax band, parking type). Null if the source data did not include any structured features. See ListingFeature for the full set of common feature IDs.
+   * Features stated in the listing as key and value pairs, covering things such as tenure and floor area. Null when the source supplied none.
    */
   features?: Array<QueryListingsFeatures> | null | undefined;
   /**
-   * Floor plan diagram images showing room layouts and approximate dimensions. May contain multiple images for multi-storey properties (one per floor). Empty array if no floor plans are available.
+   * Floor plan images showing the layout of the property, sometimes one per storey. Empty when there are none. Returned only to API keys entitled to listing media.
    */
   floorPlanImages?: Array<QueryListingsFloorPlanImages> | undefined;
   /**
-   * System-generated UUID that uniquely identifies this listing record. Stable across updates — the same listing retains its ID even when price or status changes.
+   * Identifier for this listing. It stays the same across updates, so a listing keeps its identifier when the price or status changes.
    */
   id: string;
   /**
-   * Property photography images (exterior shots, room photos, garden views, etc.). Ordered by the agent's preferred display sequence. Images are hosted on provider CDNs and are publicly accessible. Empty array if no photographs are available.
+   * Photographs of the property, in the order the source supplied them. Empty when there are none. Returned only to API keys entitled to listing media.
    */
   images?: Array<QueryListingsImages> | undefined;
   /**
-   * Whether this property is being sold via auction rather than private treaty. Auction properties typically require exchange of contracts on the fall of the hammer and completion within 28 days.
+   * True when the property is being sold at auction rather than by private treaty.
    */
   isAuction?: boolean | undefined;
   /**
-   * Whether this is a newly constructed property that has not previously been occupied. New-build properties may be available off-plan (before construction is complete) and often qualify for government schemes such as Help to Buy.
+   * True when the property is newly built and has not been lived in before.
    */
   isNewBuild?: boolean | undefined;
   /**
-   * Whether this is an age-restricted retirement or sheltered housing property. Retirement properties typically have minimum age requirements (usually 55+) and may include communal facilities.
+   * True when the property is age-restricted retirement or sheltered housing.
    */
   isRetirement?: boolean | undefined;
   /**
-   * Whether this listing is offered under a shared ownership scheme, where the buyer purchases a percentage share (typically 25-75%) and pays rent on the remainder to a housing association. Common in affordable housing programmes.
+   * True when the property is offered under a shared ownership scheme, where the buyer owns a share and pays rent on the rest.
    */
   isSharedOwnership?: boolean | undefined;
   /**
-   * The listing's unique reference within the source provider's system. Combined with 'provider', this forms a globally unique source reference. Typically a numeric or alphanumeric ID assigned by the portal.
+   * The listing's own reference within the provider's system. Together with `provider` it names one source record.
    */
   key: string;
   /**
-   * WGS84 latitude of the property location in decimal degrees. May represent an approximate position (e.g. postcode centroid) rather than the exact building location.
+   * Latitude of the property in WGS84 decimal degrees.
    */
   lat?: number | undefined;
   /**
-   * WGS84 longitude of the property location in decimal degrees. May represent an approximate position (e.g. postcode centroid) rather than the exact building location.
+   * Longitude of the property in WGS84 decimal degrees.
    */
   lng?: number | undefined;
   /**
-   * Internal location identifier used for geographic grouping, typically derived from the property's postcode (spaces removed, e.g. 'SW1A1AA'). Used to link listings to location-level analytics and nearby properties.
+   * Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN). Null when the listing has not been matched to a location.
    */
   locationId?: string | null | undefined;
   /**
-   * Marketing description text blocks authored by the estate agent, categorised by type (summary, full description, features list, location guide). Null if no descriptive content was available in the source feed.
+   * The marketing text written by the agent, split into blocks by what each one covers. Null when the source supplied none.
    */
   narratives?: Array<QueryListingsNarratives> | null | undefined;
   /**
-   * Current listing price in GBP pence. Divide by 100 to convert to pounds sterling. For sale listings: the asking price (e.g. 50000000 = £500,000). For rental listings: the monthly rent per calendar month (e.g. 150000 = £1,500 pcm). Always reflects the most recent price after any revisions. May be null/absent when the source feed does not expose a price.
+   * Current price for the listing, in pounds: the asking price for a sale, or the rent for a rental. It reflects the most recent revision. Null when the source publishes no price.
    */
   price?: number | null | undefined;
   /**
-   * Chronological history of price changes since the listing was first published. Each entry records a revision event with the old and new prices. Useful for tracking asking-price reductions and market sentiment. Ordered from earliest to most recent change.
+   * Price revisions recorded against the listing, one entry per change. Use it to track asking-price cuts and increases over time.
    */
   priceHistory?: Array<QueryListingsPriceHistory> | undefined;
   /**
-   * Primary property type classification, normalised from provider-specific taxonomies to the canonical PROPERTY_TYPE_MAPPING_VALUES set: unknown, other, flat, detached, semiDetached, terraced, bungalow, maisonette, cottage, chalet, lodge, mobileHome, houseboat, retirement, characterProperty, blockOfFlats, houseShare, farmhouse, mill, barn, coachHouse, statelyHome, farm, parking, equestrian, restaurant, industrial, warehouse, leisure, retail, land, office, riad, hotel, studentAccommodation, commercial, pub, bar, hotelRoom, shop, retailHighStreet, retailOutOfTown, industrialDevelopment, distributionWarehouse, industrialPark, storage, servicedOffice, residentialDevelopment, commercialDevelopment, mixedUse. This is a free-form string (not schema-enforced) and may occasionally contain non-standard entries.
+   * What kind of property this is, standardised from each provider's own wording to one set of values: unknown, other, flat, detached, semiDetached, terraced, bungalow, maisonette, cottage, chalet, lodge, mobileHome, houseboat, retirement, characterProperty, blockOfFlats, houseShare, farmhouse, mill, barn, coachHouse, statelyHome, farm, parking, equestrian, restaurant, industrial, warehouse, leisure, retail, land, office, riad, hotel, studentAccommodation, commercial, pub, bar, hotelRoom, shop, retailHighStreet, retailOutOfTown, industrialDevelopment, distributionWarehouse, industrialPark, storage, servicedOffice, residentialDevelopment, commercialDevelopment, mixedUse. The field is a plain string rather than a fixed enumeration, so an occasional value outside that set is possible.
    */
   propertyType: string;
   /**
-   * Identifier for the data provider or property portal that supplied this listing (e.g. a feed aggregator or portal). Used alongside 'key' to form a unique composite reference to the source record.
+   * Identifier for the data provider that supplied this listing. Together with `key` it names one source record.
    */
   provider: string;
   /**
-   * ISO 8601 datetime when the listing was first published or appeared on the source portal. This date remains unchanged even if the listing is subsequently updated.
+   * When the listing was first published by the source, as an ISO 8601 timestamp. It does not change when the listing is later updated.
    */
   publishedDate: Date;
   /**
-   * Number of reception rooms (living rooms, dining rooms, sitting rooms) as advertised by the agent. This is a UK-specific property metric. Null if not specified in the listing.
+   * Number of reception rooms advertised, meaning the living, dining and sitting rooms. Null when the listing does not state one.
    */
   receptions?: number | null | undefined;
   /**
-   * ISO 8601 datetime when the listing was removed from the source portal, or null if the listing is still active. A removed date typically indicates the property has been sold, let, or withdrawn from the market.
+   * When the listing was removed from the source, as an ISO 8601 timestamp. Null while the listing is still there.
    */
   removedDate?: Date | null | undefined;
   /**
-   * GeoJSON Point geometry representing the property's geographic location. Coordinates are in WGS84 (EPSG:4326) as [longitude, latitude]. May be null if the property could not be geocoded. Accuracy varies — some coordinates represent postcode centroids rather than exact property positions.
+   * Where the property sits, as a GeoJSON Point. Null when the listing carries no coordinates.
    */
   spatial?: QueryListingsGeoJSONPoint | null | undefined;
   /**
-   * Current status of the listing. 'live': actively marketed on one or more property portals. 'archived': listing was taken off market by the agent but retained for historical analysis (e.g. price comparisons). 'removed': listing has been permanently withdrawn or the source feed no longer includes it. Typical lifecycle: live -> archived -> removed.
+   * Where the listing stands in its marketing life. 'live': currently being marketed. 'removed': withdrawn, or no longer present in the source feed.
    */
   status: QueryListingsStatus;
   /**
-   * Secondary property type qualifier providing additional architectural or style context (e.g. 'Victorian', 'Georgian', 'Purpose Built', 'Conversion', 'Studio'). Null when the source data does not provide a sub-classification.
+   * Further detail on the kind of property, such as its period or style. Null when the source gives no such detail.
    */
   subPropertyType?: string | null | undefined;
   /**
-   * Market type for the listing. 'sale': property is listed for purchase — the price field represents the asking price in GBP pence. 'rent': property is listed for tenancy — the price field represents the monthly rental amount in GBP pence (per calendar month).
+   * Whether the property is advertised for sale or to rent. This governs how to read the price: an asking price for 'sale', the rent quoted by the source for 'rent'.
    */
   type: QueryListingsType;
   /**
-   * ISO 8601 datetime when this listing record was last modified in our system. Updated whenever any field changes, including price revisions, status transitions, or image additions.
+   * When this listing was last updated, as an ISO 8601 timestamp. It moves whenever any field changes, including price revisions, status changes and new images.
    */
   updatedAt?: Date | undefined;
   additionalProperties?: { [k: string]: any } | undefined;
 };
 
 /**
- * Object type identifier
+ * Object type discriminator. Always `list`.
  */
 export const QueryListingsObject = {
   List: "list",
 } as const;
 /**
- * Object type identifier
+ * Object type discriminator. Always `list`.
  */
 export type QueryListingsObject = ClosedEnum<typeof QueryListingsObject>;
 
 /**
- * Paginated response containing a list of property listings. Includes pagination metadata (total_count, has_more) following the Stripe-style list envelope pattern.
+ * One page of property listings, with the counters needed to fetch the rest.
  */
 export type QueryListingsResponseBody = {
   /**
-   * Array of items
+   * The items on this page.
    */
   data: Array<QueryListingsData>;
   /**
-   * Whether more items exist
+   * True when further items exist beyond this page.
    */
   hasMore: boolean;
   /**
-   * Object type identifier
+   * Object type discriminator. Always `list`.
    */
   object: QueryListingsObject;
   /**
-   * Total number of items available
+   * Total number of items matching the request across all pages.
    */
   totalCount?: number | undefined;
   /**
-   * URL of the request
+   * Path this list was requested from.
    */
   url: string;
 };