# Listing # Listing Listing-data ingestion: bulk feeds, incremental updates, and normalisation of price, commission and sale history. Two ingestion modes. A bulk feed loads the market's full inventory; an incremental extract picks up what changed since the last run. Both land in the same canonical listing classes. Listing history is kept as a timeline rather than as a current state. A price reduction and its date are the signal; the current asking price alone is not. ## How it works Listing data is treated as evidence about the market rather than as fact about the property. Physical characteristics come from the assessor record in Property; what the listing contributes is price, timing and the agent's account of condition. ## Operations ### Address Autocomplete `GET` `/api/address-autocomplete` #### Address Autocomplete `addressAutocomplete` Provide address autocomplete suggestions using Typesense database. ##### Response 200400404 application/json Copy Success ``` { "result": [ { "full_address": "1303 North 24th Street, Fort Pierce, FL 34950-5706, USA", "listing_identifier": "RX-10996641" } ] } ``` application/json Copy Parsing error ``` { "message": "Something went wrong while parsing data." } ``` application/json Copy Not Found ``` { "message": "Not Found" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `address` required | `string` query | `1303 N 24th St` | Address to search suggestions for. | ##### Response `200``application/json` 1 fields Success | Field | Type | Description | | --- | --- | --- | | `result` | `object[]` | Address suggestions | | `highlight` | `string` | Highlighted addressExample `18419 SE Wood Haven Ln Jupiter FL 33469` | | `address_identifier` | `string` | Address identifierExample `1` | | `full_address` | `string` | Full addressExample `1303 North 24th Street, Fort Pierce, FL 34950-5706, USA` | | `mls_number_identifier` | `string` | Listing identifierExample `RX-10996641` | ##### Other responses `400``404` ### Featured Listings `GET` `/api/featured-listings` #### List Featured Listings `listFeaturedListings` ##### Response application/json Copy Success ``` { "total_listings": 13, "listings": [ { "id": "R10948321", "bathroom_count": 5, "bedroom_count": 6, "price": "$5600000", "photo_links": [ "https://dev-data-manager-blobs-bucket-us-east-1-284201000534.s3.amazonaws.com/01J0RAA48B3V8R3H6E2ABKADX7.csv?" ], "size_sqft": 16174, "address": { "number": "17392", "direction": "S", "name": "Beach Rd", "city": "Jupiter", "state": "Florida", "stateabrv": "FL", "unit_identifier": null, "zip": "33478" } } ], "page": 5, "limit": 1 } ``` ##### Response `200``application/json` 4 fields Success | Field | Type | Description | | --- | --- | --- | | `total_listings` | `integer` | Number of propertiesExample `500` | | `listings` | `object[]` | Listings | | `id` | `string` | Listing IdentifierExample `R10960478` | | `bathroom_count` | `integer` | Bathroom CountExample `11` | | `bedroom_count` | `integer` | Bedroom CountExample `6` | | `price` | `string` | Property priceExample `$74,950,000` | | `photo_links` | `string[]` | Status | | `size_sqft` | `integer` | Size of the propertyExample `19666` | | `address` | `object` | Address of the property | | `page` | `integer` | Page of searchExample `1` | | `limit` | `integer` | Count of returned listingsExample `5` | ### Verified Listings[new] `GET` `/api/listings` #### List Listings `listListings` ##### Response 200400 application/json Copy Success ``` { "total_listings": 500, "listings": [ { "id": "R10960478", "bathroom_count": 11, "bedroom_count": 6, "price": "$74,950,000", "photo_links": [ "https://api-trestle.corelogic.com/trestle/Media/FTL.FTL_RMLS/Property/PHOTO-jpeg/1061293103/1/MzczLzE5MTEvMjA/MjAvNTg4MS8xNzE0NTExNzAz/VyYmk00oHFgbkHESRbSVGqgKvoQrLVhMDkfeiOQSJGk" ], "size_sqft": 19666 } ], "page": 1, "limit": 1 } ``` application/json Copy Parsing error ``` { "message": "Something went wrong while parsing data." } ``` ##### Response `200``application/json` 4 fields Success | Field | Type | Description | | --- | --- | --- | | `total_listings` | `integer` | Number of propertiesExample `500` | | `listings` | `object[]` | Listings | | `id` | `string` | Listing IdentifierExample `R10960478` | | `bathroom_count` | `integer` | Bathroom CountExample `11` | | `bedroom_count` | `integer` | Bedroom CountExample `6` | | `price` | `string` | Property priceExample `$74,950,000` | | `photo_links` | `string[]` | Status | | `size_sqft` | `integer` | Size of the propertyExample `19666` | | `page` | `integer` | Page of searchExample `1` | | `limit` | `integer` | Count of returned listingsExample `5` | ##### Other responses `400` `POST` `/api/delete-search-cache` #### Delete Search Cache `deleteSearchCache` Execute Search Cache Deletion. This operation clean up address search cache and list listings v2 CloudFront cache. ##### Response application/json Copy Success ``` { "operation_id": "01F7S0NA7CQ31DZQYVSVPN66GNK", "operation_status": "In Progress" } ``` ##### Response `200``application/json` 2 fields Success | Field | Type | Description | | --- | --- | --- | | `operation_id` | `string` | Operation identifierExample `01F7S0NA7CQ31DZQYVSVPN66GNK` | | `operation_status` | `string` | Operation statusExample `In Progress` | `PUT` `/commissions` #### Upload Commissions `uploadCommission` Update DynamoDB with new MLS commissions. ##### Response application/json Copy Success ``` { "presigned_url": "https://verified-listings-search-dev-listingsbucket-tazledfrubic.s3.amazonaws.com/commission/20240704/update.csv?AWSAccessKeyId=&Signature=&content-type=text%2Fcsv&x-amz-security-token=&Expires=1720100100" } ``` ##### Response `200``application/json` 1 fields Success | Field | Type | Description | | --- | --- | --- | | `presigned_url` | `string` | Link for table PUT item operationExample `https://verified-listings-search-dev-listingsbucket-tazledfrubic.s3.amazonaws.com/commission/20240704/update.csv?AWSAccessKeyId=&Signature=&content-type=text%2Fcsv&x-amz-security-token=&Expires=1720100100` | `GET` `/listing/{id}` #### Search `listingsSearchId` Get Listing Get raw data from IDX. ##### Response application/json Copy Success ``` { "listing": { "street": "8346 NW 118 Way", "city": "Coral Springs", "state": "Florida", "zipcode": "33076", "status": "Active", "price": "800000", "bathroom_count": "2", "bedroom_count": "3", "lease_price": null, "sale_price": null, "square_footage": "1904", "sold_date": null, "description": "Turn key*Quick closing ok* immaculate Single Family Home with serene wide water views located in a Guard Gated Golf course Cmnty* Impact Glass* potential to convert to a 4 Bedroom* Tile in living areas* wood in one room* Tankless gas Wtr Htr* Gas Range for gourmet cooking* Snack Bar Island w/sink* SS Appliances* Granite counters & 42 inch Cabinets* high volume ceilings, recessed lighting* knockdown texture* crown molding*some coffered ceilings* Master has a Huge walk in closet * amenities galore* close to shopping, places of worship, schools, parks, Equestrian center and much more*", "primary_features": { "county": "Broward County", "partial_bathrooms": null, "property_sub_type": "Single Family Residence", "property_type": "Residential", "subdivision": "Somerset", "year_built": "2013" }, "interior": { "appliances": "Some Gas Appliances, Dryer, Dishwasher, Disposal, Gas Range, Gas Water Heater, Microwave, Refrigerator, Washer", "building_area_total": "2574", "cooling": "Central Air, Ceiling Fan(s), Electric", "fireplace_features": null, "flooring": "Carpet, Ceramic Tile, Tile, Wood", "heating": "Central, Electric", "interior_features": "Breakfast Bar, Dual Sinks, High Ceilings, Living/Dining Room, Main Level Primary, Pantry, Split Bedrooms, Separate Shower, Walk-In Closet(s), Attic", "spa_features": null, "stories_total": null }, "external": { "construction_materials": "Block, Other", "covered_spaces": "2", "door_features": null, "exterior_features": "Enclosed Porch, Security/High Impact Doors", "garage_spaces": "2", "lot_features": "Other, Sprinklers Automatic, < 1/4 Acre", "lot_size_area": "6841", "lot_size_square_feet": "6841", "parking_features": "Attached, Driveway, Garage", "patio_and_porch_features": "Porch, Screened", "pool_features": "None, Community", "roof": "Spanish Tile", "sewer": "Public Sewer", "utilities": "Cable Available", "water_source": "Public", "window_features": "Blinds, Drapes, Impact Glass" }, "location": { "association_amenities": null, "community_features": "Clubhouse, Gated, Home Owners Association, Pool", "complex_name": null, "elementary_school": "Heron Heights", "mls_area_major": "3614", "mls_area_minor": "North Broward 441 To Everglades (3611-3642)", "postal_city": "Coral Springs", "view": "Canal, Water", "waterfront_features": "Canal Front", "zoning_description": "RS-6" }, "additional": { "builder_model": "Azalea", "housing_older_persons_act": "No HOPA", "mls_status": "Active", "pets_allowed": "Size Limit, Yes", "property_condition": "Resale", "property_sub_type_additional": "Single Family Residence", "security_features": "Smoke Detector(s)", "year_built_details": "Resale" }, "financial": { "association_fee": "838", "association_fee_frequency": "Quarterly", "association_fee_includes": "Common Area Maintenance, Recreation Facilities, Security", "disclosures": null, "listing_terms": "Conventional", "possession": "Closing & Funding", "special_listing_conditions": "Listed As-Is", "tax_annual_amount": "9611", "tax_year": "2023" } } } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `id` required | `string` path | `R10823327` | ID of the listing to get. | ##### Response `200``application/json` 1 fields Success | Field | Type | Description | | --- | --- | --- | | `listing` | `object` | Listing object | ##### Other responses `404` `GET` `/api/delete-search-cache/{operation_id}` #### Get Search Cache Deletion Status `getDeleteSearchCacheStatus` Get the status of the search cache deletion operation. ##### Response 200400404 application/json Copy Success ``` { "operation_id": "01F7S0NA7CQ31DZQYVSVPN66GNK", "operation_status": "Completed" } ``` application/json Copy Parsing error ``` { "message": "Something went wrong while parsing data." } ``` application/json Copy Not Found ``` { "message": "Not Found" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `operation_id` required | `string` path | `01F7S0NA7CQ31DZQYVSVPN66GNK` | Operation identifier | ##### Response `200``application/json` 2 fields Success | Field | Type | Description | | --- | --- | --- | | `operation_id` | `string` | Operation identifierExample `01F7S0NA7CQ31DZQYVSVPN66GNK` | | `operation_status` | `string` | Operation statusExample `Completed` | ##### Other responses `400``404` `GET` `/api/v2/listings` #### List Listings V2 `listListingsV2` This endpoint returns a list of verified listings. The response includes the total number of listings, the listings themselves, the page number, and the limit of listings per page. This endpoint supports query parameters following this structure: `lexicon_listing_property[operator]=value`, where lexicon_listing_property is the property to filter by (staircase_discount_price_amount, current_list_price_amount, days_on_market_count), operator is the operator to use for the filter (gte, lte, eq, gt, lt), and value is the value to filter by. Show the rest Examples of query parameters: `staircase_discount_price_amount[gte]=1000000`, `current_list_price_amount[lt]=500000`, `days_on_market_count[eq]=30`, `featured_home_indicator[eq]=true`, `deals_home_indicator[eq]=true`, `pets_allowed_indicator[eq]=true`, `private_pool_indicator[eq]=true`, `gated_community_indicator[eq]=true`, `school_indicator[eq]=true`, `water_front_indicator[eq]=true`, `garage_spaces[gte]=0`. To perform Radius search to retrieve all of the listings around a desired location by specific radius provide the following: - Latitude of the location. - Longitude of the location. - Radius that will be used to perform search. - Number of listings to retrieve while performing search Note: if the provided Radius return number of listings that is less than the expected number, the radius will automatically increase by 1 mi, until the desired number of listings reached or max radius of 50 mi reached. Examples of query parameters: `latitude=26.6755617`,`longitude=-80.2620304`,`radius=5`,`number_of_listings=50` ##### Response 200400 application/json Copy Success ``` { "page": 1, "limit": 10, "total_listings": 10, "listings": [ { "id": "FX-10397327", "bathroom_count": 5, "bedroom_count": 6, "price": "$5,600,000", "photo_links": [ "photo_link" ], "size_sqft": 16174, "address": { "number": "8531", "direction": "SW", "unit_identifier": null, "name": "18th Pl", "city": "Davie", "state": "Florida", "stateabrv": "FL", "zip": "33324" }, "featured": true, "discounted_price": "$25,000.0" } ] } ``` application/json Copy Parsing error ``` { "message": "Something went wrong while parsing data." } ``` ##### Parameters 15 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `ids_only` | `boolean` query | `true` | Return only listing IDs. | | `listing_id` | `string[]` query | — | MLS Listing IDs to filter by. | | `page` required | `integer` query | `1` | Page number. | | `limit` required | `integer` query | `10` | Number of listings per page. | | `address` | `string` query | `8531 SW 18th Pl` | Filter by address. | | `place_id` | `string` query | `ChIJwUv6v3vX2YgR5Z9Zk1YF1ZQ` | Filter by Google place ID. | | `city_name` | `string` query | `Boca Raton` | Filter by city name. | | `postal_code` | `string` query | `33431` | Filter by postal code. | | `location` | `string` query | `PalmBeach` | Filter by location. | | `sort_by` | `string` query | `listing_price` | Sort by field. | | `sort_order` | `string` query | `asc` | Sort order. | | `latitude` | `string` query | `26.6755617` | The latitude of the location. | | `longitude` | `string` query | `-80.2620304` | The longitude of the location. | | `radius` | `string` query | `2` | Radius used in radius search in Miles. | | `number_of_listings` | `string` query | `100` | Number of listings required while performing radius search. | ##### Response `200``application/json` 4 fields Success | Field | Type | Description | | --- | --- | --- | | `total_listings` | `integer` | Number of propertiesExample `500` | | `listings` | `object[]` | Listings | | `page` | `integer` | Page of searchExample `1` | | `limit` | `integer` | Count of returned listingsExample `5` | ##### Other responses `400` `GET` `/api/google-reviews` #### Get Google Reviews `getGoogleReviews` This endpoint returns a list of Google reviews for Staircase business place from Google Maps. ##### Response application/json Copy Success ``` { "total_reviews": 6, "average_rating": 4.8, "reviews": [ { "name": "places/abc/reviews/abc", "author": "John Doe", "author_uri": "https://www.google.com/maps", "author_photo": "https://lh3.googleusercontent.com", "rating": 5, "publish_time": "2018-12-22T11:41:04Z", "relative_publish_time": "5 years ago", "text": "Some review text" } ] } ``` ##### Response `200``application/json` 3 fields Success | Field | Type | Description | | --- | --- | --- | | `total_reviews` | `integer` | Number of reviewsExample `6` | | `average_rating` | `number` | Average ratingExample `4.8` | | `reviews` | `object[]` | Reviews | | `name` | `string` | Review identifierExample `places/abc/reviews/abc` | | `author` | `string` | Review authorExample `John Doe` | | `author_uri` | `string` | Review author URIExample `https://www.google.com/maps` | | `author_photo` | `string` | Review author photoExample `https://lh3.googleusercontent.com` | | `rating` | `number` | Review ratingExample `5` | | `publish_time` | `string` | Review publish timeExample `2018-12-22T11:41:04Z` | | `relative_publish_time` | `string` | Relative publish timeExample `5 years ago` | | `text` | `string` | Review textExample `Some review text` | `GET` `/api/inst-posts` #### Get Instagram Posts `getInstagramPosts` This endpoint returns a list of posts from the Instagram Staircase page. ##### Response application/json Copy Success ``` { "instagram_posts": [ { "ig_link": "https://www.instagram.com/p/C3jbJXKNdgO", "post_url": "download_url" } ] } ``` ##### Response `200``application/json` 1 fields Success | Field | Type | Description | | --- | --- | --- | | `instagram_posts` | `object[]` | List of Instagram posts | | `ig_link` | `string` | URL of the Instagram post on the Instagram websiteExample `https://www.instagram.com/p/C3jbJXKNdgO` | | `post_url` | `string` | URL of the downloadable Instagram post contentExample `download_url` | ### Listings-Save-Customer-Data `POST` `/mortgage-rate` #### Save Mortgage Rate `saveMortgageRate` ##### Request application/json Copy ``` { "transaction_id": "12345", "monthly_payment": 1000, "usage_type": "Primary", "fico": 720, "email_frequency": "Monthly" } ``` ##### Response application/json Copy Success ``` { "message": "Data saved successfully" } ``` ##### Request body`application/json` 5 fields | Field | Type | Description | | --- | --- | --- | | `transaction_id`required | `string` | Unique identifier for the transaction. | | `monthly_payment`required | `integer` | Monthly payment amount for the mortgage. | | `usage_type`required | `string` | Type of property usage, such as Primary, Secondary, or Investment. | | `fico`required | `integer` | FICO credit score of the borrower. | | `email_frequency`required | `string` | Frequency of email notifications, e.g., Monthly or Weekly. | ##### Response `200``application/json` 1 fields Success | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Success message indicating data was saved.Example `Data saved successfully` | `POST` `/buy-search` #### Save Buy Search `saveBuySearch` ##### Request application/json Copy ``` { "transaction_id": "12345", "email_frequency": "Monthly", "search_name": "My Search" } ``` ##### Response application/json Copy Success ``` { "message": "Data saved successfully" } ``` ##### Request body`application/json` 3 fields | Field | Type | Description | | --- | --- | --- | | `transaction_id`required | `string` | Unique identifier for the transaction. | | `email_frequency`required | `string` | Frequency of email notifications, e.g., Monthly or Weekly. | | `search_name`required | `string` | Name of the search. | ##### Response `200``application/json` 1 fields Success | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Success message indicating data was saved.Example `Data saved successfully` | `POST` `/sell-tracking` #### Save Sell Tracking `saveSellTracking` ##### Request application/json Copy ``` { "transaction_id": "12345", "email_frequency": "Monthly", "address": "123 Main St." } ``` ##### Response application/json Copy Success ``` { "message": "Data saved successfully" } ``` ##### Request body`application/json` 3 fields | Field | Type | Description | | --- | --- | --- | | `transaction_id`required | `string` | Unique identifier for the transaction. | | `email_frequency`required | `string` | Frequency of email notifications, e.g., Monthly or Weekly. | | `address`required | `string` | Address of the property. | ##### Response `200``application/json` 1 fields Success | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Success message indicating data was saved.Example `Data saved successfully` | ### Verified-Properties-Search `GET` `/properties/{address}` #### Get Property `getProperty` ##### Response 200404 application/json Copy Success ``` { "property": { "street": "8346 NW 118 Way", "city": "Coral Springs", "state": "Florida", "zipcode": "33076", "status": "Active", "price": "800000", "bathroom_count": "2", "bedroom_count": "3", "lease_price": null, "sale_price": null, "square_footage": "1904", "sold_date": null, "description": "Turn key*Quick closing ok* immaculate Single Family Home with serene wide water views located in a Guard Gated Golf course Cmnty* Impact Glass* potential to convert to a 4 Bedroom* Tile in living areas* wood in one room* Tankless gas Wtr Htr* Gas Range for gourmet cooking* Snack Bar Island w/sink* SS Appliances* Granite counters & 42 inch Cabinets* high volume ceilings, recessed lighting* knockdown texture* crown molding*some coffered ceilings* Master has a Huge walk in closet * amenities galore* close to shopping, places of worship, schools, parks, Equestrian center and much more*", "primary_features": { "county": "Broward County", "partial_bathrooms": null, "property_sub_type": "Single Family Residence", "property_type": "Residential", "subdivision": "Somerset", "year_built": "2013" }, "interior": { "appliances": "Some Gas Appliances, Dryer, Dishwasher, Disposal, Gas Range, Gas Water Heater, Microwave, Refrigerator, Washer", "building_area_total": "2574", "cooling": "Central Air, Ceiling Fan(s), Electric", "fireplace_features": null, "flooring": "Carpet, Ceramic Tile, Tile, Wood", "heating": "Central, Electric", "interior_features": "Breakfast Bar, Dual Sinks, High Ceilings, Living/Dining Room, Main Level Primary, Pantry, Split Bedrooms, Separate Shower, Walk-In Closet(s), Attic", "spa_features": null, "stories_total": null }, "external": { "construction_materials": "Block, Other", "covered_spaces": "2", "door_features": null, "exterior_features": "Enclosed Porch, Security/High Impact Doors", "garage_spaces": "2", "lot_features": "Other, Sprinklers Automatic, < 1/4 Acre", "lot_size_area": "6841", "lot_size_square_feet": "6841", "parking_features": "Attached, Driveway, Garage", "patio_and_porch_features": "Porch, Screened", "pool_features": "None, Community", "roof": "Spanish Tile", "sewer": "Public Sewer", "utilities": "Cable Available", "water_source": "Public", "window_features": "Blinds, Drapes, Impact Glass" }, "location": { "association_amenities": null, "community_features": "Clubhouse, Gated, Home Owners Association, Pool", "complex_name": null, "elementary_school": "Heron Heights", "mls_area_major": "3614", "mls_area_minor": "North Broward 441 To Everglades (3611-3642)", "postal_city": "Coral Springs", "view": "Canal, Water", "waterfront_features": "Canal Front", "zoning_description": "RS-6" }, "additional": { "builder_model": "Azalea", "housing_older_persons_act": "No HOPA", "mls_status": "Active", "pets_allowed": "Size Limit, Yes", "property_condition": "Resale", "property_sub_type_additional": "Single Family Residence", "security_features": "Smoke Detector(s)", "year_built_details": "Resale" }, "financial": { "association_fee": "838", "association_fee_frequency": "Quarterly", "association_fee_includes": "Common Area Maintenance, Recreation Facilities, Security", "disclosures": null, "listing_terms": "Conventional", "possession": "Closing & Funding", "special_listing_conditions": "Listed As-Is", "tax_annual_amount": "9611", "tax_year": "2023" } } } ``` application/json Copy Not Found ``` { "error": "Not Found" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `address` required | `string` path | `5730-royal-club-drive-boynton-beach-fl-33437-4265-usa` | full address slug | ##### Response `200``application/json` 1 fields Success | Field | Type | Description | | --- | --- | --- | | `property` | `object` | Property object | ##### Other responses `404` ### Sitemap-Listings-Update-Service `POST` `/run-update` #### Run Update `runUpdate` ##### Response application/json Copy Ok. ``` { "status": "Ok" } ``` ##### Response `200``application/json` 1 fields Ok. | Field | Type | Description | | --- | --- | --- | | `status` | `string` | Status of the transaction | ## Canonical model - `address` - `property` - `address` - `property` ## Property data it reads - address - property ## Errors `400``404` ## More in Assessment - Previous product: Appraisal - Next product: Property