Search

Search and discover real estate data by city, neighborhood, and marketplace listings. Use these endpoints to list cities and neighborhoods, validate locations, fetch top markets, investment performance, and property listings.

GET/v1.1/client/city/list

List Cities

This endpoint retrieves the list of cities in a specific state.

Query parameters

Name
state
Type
string
Description
Two-letter state code (e.g. FL, NV).
Name
page
Type
integer
Description
Page number. Default: 1.
Name
items
Type
integer
Description
Items per page. Default: 10. Max: 10.

Request

GET

/v1.1/client/city/list

curl -G "https://api.mashvisor.com/v1.1/client/city/list?state=FL" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "status": "success",
  "content": {
    "count": 726,
    "list": [
      "Alachua",
      "Alford",
      "ALLIGATOR POINT",
      "Altamonte Springs",
      "ALTHA",
      "ALTOONA",
      "ALTURAS",
      "Alva",
      "ANNA MARIA",
      "Anthony"
    ]
  }
}

GET/v1.1/client/metadata/validate-city

Validate City Name

Validates a city name in a specific state and returns suggestions if the city does not exist. Drop "city" or "town" suffixes per naming rules.

Query parameters

Name
state
Type
string
Description
Two-letter state code (e.g. PA, NV).
Name
city
Type
string
Description
City name (e.g. Los Angeles, Ashville City).

Request

GET

/v1.1/client/metadata/validate-city

curl -G "https://api.mashvisor.com/v1.1/client/metadata/validate-city" \
  --data-urlencode "state=PA" \
  --data-urlencode "city=Ashville City" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "status": "success",
  "content": {
    "input": {
      "state": "PA",
      "city": "Ashville City"
    },
    "exists": false,
    "canonical_city": "Ashville",
    "suggestions": ["Ashville"],
    "note": "Drop 'city/town' suffixes per naming rules."
  },
  "message": "success"
}

GET/v1.1/client/city/neighborhoods/:state/:city

List Neighborhoods

Retrieves all available neighborhoods or areas for a given city.

Path parameters

Name
state
Type
string
Description
Two-letter state code (e.g. CA, NV).
Name
city
Type
string
Description
City name (e.g. Los Angeles). URL-encode spaces.

Request

GET

/v1.1/client/city/neighborhoods/CA/Los Angeles

curl "https://api.mashvisor.com/v1.1/client/city/neighborhoods/CA/Los%20Angeles" \
-H "x-api-key: YOUR_API_KEY"

Response

{
  "status": "success",
  "content": {
    "count": 96,
    "results": [
      {
        "id": 7877,
        "city": "Los Angeles",
        "latitude": 33.952138,
        "longitude": -118.404407,
        "name": "Westchester",
        "state": "CA",
        "county": "Los Angeles",
        "is_village": 0
      },
      {
        "id": 13017,
        "city": "Los Angeles",
        "latitude": 34.238792,
        "longitude": -118.477272,
        "name": "North Hills",
        "state": "CA",
        "county": "Los Angeles",
        "is_village": 0
      },
      {
        "id": 13176,
        "city": "Los Angeles",
        "latitude": 34.228894,
        "longitude": -118.444025,
        "name": "Panorama City",
        "state": "CA",
        "county": "Los Angeles",
        "is_village": 0
      },
      {
        "id": 13327,
        "city": "Los Angeles",
        "latitude": 33.974969,
        "longitude": -118.420888,
        "name": "Playa Vista",
        "state": "CA",
        "county": "Los Angeles",
        "is_village": 0
      }
    ]
  },
  "message": "City neighborhoods list fetched successfully"
}

GET/v1.1/client/city/top-markets

List Top Markets

Retrieves top cities or metro areas in a state with a count of active homes for sale.

Query parameters

Name
state
Type
string
Description
Two-letter state code (e.g. GA, NV).
Name
items
Type
integer
Description
Number of items to return. Default: 5.

Request

GET

/v1.1/client/city/top-markets

curl -G "https://api.mashvisor.com/v1.1/client/city/top-markets?state=GA" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "status": "success",
  "content": [
    {
      "city": "Atlanta",
      "state": "GA",
      "smart_location": "Atlanta, GA",
      "homes_for_sale": 5688
    },
    {
      "city": "Athens",
      "state": "GA",
      "smart_location": "Athens, GA",
      "homes_for_sale": 1132
    },
    {
      "city": "Macon",
      "state": "GA",
      "smart_location": "Macon, GA",
      "homes_for_sale": 1017
    },
    {
      "city": "Savannah",
      "state": "GA",
      "smart_location": "Savannah, GA",
      "homes_for_sale": 907
    },
    {
      "city": "Marietta",
      "state": "GA",
      "smart_location": "Marietta, GA",
      "homes_for_sale": 780
    }
  ],
  "message": "Top markets list fetched successfully"
}

GET/v1.1/client/city/investment/:state/:city

Get City Investment Performance

Retrieves median property performance metrics for a city (e.g. occupancy, cap rate, rental rates).

Path parameters

Name
state
Type
string
Description
Two-letter state code (e.g. CA).
Name
city
Type
string
Description
City name (e.g. Los Angeles). URL-encode spaces.

Request

GET

/v1.1/client/city/investment/CA/Los Angeles

curl "https://api.mashvisor.com/v1.1/client/city/investment/CA/Los%20Angeles" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "status": "success",
  "content": {
    "median_price": 1050000,
    "sqft": 2670.89,
    "investment_properties": 4842,
    "airbnb_properties": 6597,
    "traditional_properties": 5849,
    "occupancy": 16,
    "traditional_coc": 2,
    "airbnb_coc": -1,
    "airbnb_cap_rate": 100.286,
    "traditional_cap_rate": 62.722,
    "traditional_rental": 4056,
    "airbnb_rental": 1148,
    "airbnb_rental_rates": {
      "zeroBedRoomHomeValue": 1303.85,
      "oneBedRoomHomeValue": 1172.09,
      "twoBedRoomsHomeValue": 1298.39,
      "threeBedRoomsHomeValue": 1504.27,
      "fourBedRoomsHomeValue": 1751.08
    },
    "traditional_rental_rates": {
      "zeroBedRoomHomeValue": 2058.77,
      "oneBedRoomHomeValue": 2360.25,
      "twoBedRoomsHomeValue": 3383,
      "threeBedRoomsHomeValue": 5061.53,
      "fourBedRoomsHomeValue": 6284.56
    }
  },
  "message": "City Overview fetched successfully"
}

GET/v1.1/client/city/properties/:state/:city

Get City Top Properties

Retrieves detailed data on a city's top investment properties (performance, ROI, rental income).

Path parameters

Name
state
Type
string
Description
Two-letter state code (e.g. CA).
Name
city
Type
string
Description
City name (e.g. Los Angeles). URL-encode spaces.

Request

GET

/v1.1/client/city/properties/CA/Los Angeles

curl "https://api.mashvisor.com/v1.1/client/city/properties/CA/Los%20Angeles" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "status": "success",
  "content": {
    "properties": [
      {
        "id": 3751027,
        "neighborhood": "University Hills",
        "neighborhood_id": 403190,
        "address": "986 Gifford Avenue",
        "zip_code": "90063",
        "zip": "90063",
        "city": "Los Angeles",
        "county": "Los Angeles",
        "state": "CA",
        "type": "Multi Family",
        "image_url": "https://ssl.cdn-redfin.com/photo/45/bigphoto/990/AR25054990_1_0.jpg",
        "list_price": 495000,
        "baths": 2,
        "beds": 5,
        "sqft": 1218,
        "mls_id": "AR25054990",
        "days_on_market": 30,
        "next_open_house_date": null,
        "next_open_house_start_time": null,
        "next_open_house_end_time": null,
        "last_sale_date": "2012-10-31 00:00:00",
        "last_sale_price": 167000,
        "listing_id": "AR25054990",
        "has_pool": null,
        "is_water_front": null,
        "num_of_units": 2,
        "latitude": 34.0474,
        "longitude": -118.176,
        "traditional_ROI": 4.1716,
        "airbnb_ROI": 9.3168,
        "traditional_rental": 2924,
        "airbnb_rental": 6538,
        "traditional_cap": 4.21374,
        "airbnb_cap": 9.41091,
        "neighborhood_zipcode": "90032",
        "list_price_formatted": "$495,000",
        "price_per_sqft": 406,
        "country": "United States",
        "COC": {
          "airbnb": 9.3168,
          "traditional": 4.1716
        },
        "rental_income": {
          "airbnb": 6538,
          "traditional": 2924
        },
        "cap_rate": {
          "airbnb": 9.41091,
          "traditional": 4.21374
        },
        "image": "https://ssl.cdn-redfin.com/photo/45/bigphoto/990/AR25054990_1_0.jpg"
      },
      {
        "id": 5850389,
        "neighborhood": "Mount Washington",
        "neighborhood_id": 116774,
        "address": "520 Rustic Dr",
        "zip_code": "90065",
        "zip": "90065",
        "city": "Los Angeles",
        "county": "Los Angeles",
        "state": "CA",
        "type": "Other",
        "image_url": "https://ssl.cdn-redfin.com/photo/45/bigphoto/697/WS26001697_0.jpg",
        "list_price": 124000,
        "baths": null,
        "beds": null,
        "sqft": null,
        "mls_id": "WS26001697",
        "days_on_market": 13,
        "next_open_house_date": null,
        "next_open_house_start_time": null,
        "next_open_house_end_time": null,
        "last_sale_date": null,
        "last_sale_price": null,
        "listing_id": "WS26001697",
        "has_pool": null,
        "is_water_front": null,
        "num_of_units": null,
        "latitude": 34.1052,
        "longitude": -118.209,
        "traditional_ROI": 11.7318,
        "airbnb_ROI": 8.82481,
        "traditional_rental": 1705,
        "airbnb_rental": 1856,
        "traditional_cap": 12.2048,
        "airbnb_cap": 9.18064,
        "neighborhood_zipcode": "90065",
        "list_price_formatted": "$124,000",
        "price_per_sqft": null,
        "country": "United States",
        "COC": {
          "airbnb": 8.82481,
          "traditional": 11.7318
        },
        "rental_income": {
          "airbnb": 1856,
          "traditional": 1705
        },
        "cap_rate": {
          "airbnb": 9.18064,
          "traditional": 12.2048
        },
        "image": "https://ssl.cdn-redfin.com/photo/45/bigphoto/697/WS26001697_0.jpg"
      }
    ]
  },
  "message": "City Properties fetched successfully"
}

GET/v1.1/client/city/listings

Marketplace Listings Search

Powers your real estate marketplace experience by fetching property listings across any U.S. city. Use optional filters (beds, baths, price, property type) to match users with relevant listings.

Query parameters

Name
state
Type
string
Description
Two-letter state code (e.g. CA).
Name
city
Type
string
Description
City name. Required if zip_code is not provided.
Name
beds
Type
integer
Description
Minimum number of bedrooms.
Name
baths
Type
integer
Description
Minimum number of bathrooms.
Name
min_price
Type
integer
Description
Minimum listing price.
Name
max_price
Type
integer
Description
Maximum listing price.
Name
min_sqft
Type
integer
Description
Minimum square footage.
Name
property_type
Type
string
Description
Property type (e.g. Single Family Residential, Apartment).
Name
foreclosure
Type
boolean
Description
Include foreclosed properties. Default: false.
Name
page
Type
integer
Description
Page number. Default: 1.
Name
page_limit
Type
integer
Description
Results per page. Default: 100.

Request

GET

/v1.1/client/city/listings

curl -G "https://api.mashvisor.com/v1.1/client/city/listings" \
  -d "state=CA" \
  -d "city=San Francisco" \
  -d "page=1" \
  -d "page_limit=50" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "status": "success",
  "content": {
    "total_results": 3674,
    "properties": [
      {
        "id": 6112406,
        "address": "2026 Great Hwy",
        "zip_code": "94116",
        "city": "San Francisco",
        "county": "San Francisco",
        "state": "CA",
        "neighborhood": "Outer Parkside",
        "neighborhood_id": 417517,
        "type": "Single Family Residential",
        "baths": 4,
        "beds": 3,
        "mls_id": null,
        "status": "active",
        "list_price": 5900000,
        "last_sale_price": null,
        "original_list_price": null,
        "image_url": "https://photos.zillowstatic.com/fp/6fbe698cc8307a072a61a9e7a1bca133-p_e.jpg",
        "is_foreclosure": 0,
        "sqft": 0,
        "lot_size": null,
        "latitude": 37.7486,
        "longitude": -122.508,
        "neighborhood_zipcode": "94116"
      },
      {
        "id": 6112431,
        "address": "555 Fulton St SUITE 209",
        "zip_code": "94102",
        "city": "San Francisco",
        "county": "San Francisco",
        "state": "CA",
        "neighborhood": "Hayes Valley",
        "neighborhood_id": 268206,
        "type": "Single Family Residential",
        "baths": 1,
        "beds": 1,
        "mls_id": null,
        "status": "active",
        "list_price": 321536,
        "last_sale_price": null,
        "original_list_price": null,
        "image_url": "https://photos.zillowstatic.com/fp/3528d2f9269f650daabc8c6e5988b6a2-p_e.jpg",
        "is_foreclosure": 0,
        "sqft": 491,
        "lot_size": null,
        "latitude": 37.7782,
        "longitude": -122.426,
        "neighborhood_zipcode": "94117"
      }
    ],
    "page": 1,
    "total_pages": 3674
  },
  "message": "Properties fetched successfully"
}

GET/v1.1/client/trends/neighborhoods

Get Top Neighborhoods

Retrieves the top neighborhoods by occupancy rate in a specific city and state.

Query parameters

Name
state
Type
string
Description
Two-letter state code (e.g. FL).
Name
city
Type
string
Description
City name (e.g. Miami Beach).
Name
page
Type
integer
Description
Page number. Default: 1.
Name
items
Type
integer
Description
Number of neighborhoods to return. Default: 5.

Request

GET

/v1.1/client/trends/neighborhoods

curl -G "https://api.mashvisor.com/v1.1/client/trends/neighborhoods" \
  -d "state=FL" \
  -d "city=Miami Beach" \
  -d "items=3" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "status": "success",
  "content": {
    "total_results": 3,
    "current_page": 1,
    "state": "FL",
    "city": "Miami Beach",
    "neighborhoods": [
      {
        "id": 407493,
        "name": "North Shore",
        "city": "Miami Beach",
        "state": "FL",
        "occupancy": 27,
        "total_listing": 1,
        "airbnb_listings": 84,
        "description": null,
        "single_home_value": 578434,
        "single_home_value_formatted": "$578,434",
        "investment_rentals": {
          "airbnb_rental": {
            "roi": -2.54341,
            "cap_rate": 3.3072744686515665,
            "rental_income": 1594.2
          },
          "traditional_rental": {
            "roi": 1.69629,
            "cap_rate": 12.090575588571904,
            "rental_income": 5828
          }
        },
        "mashMeter": 31
      },
      {
        "id": 124846,
        "name": "Isle of Normandy",
        "city": "Miami Beach",
        "state": "FL",
        "occupancy": 29,
        "total_listing": 1,
        "airbnb_listings": 36,
        "description": null,
        "single_home_value": 887657,
        "single_home_value_formatted": "$887,657",
        "investment_rentals": {
          "airbnb_rental": {
            "roi": -1.34213,
            "cap_rate": 1.6769991111431557,
            "rental_income": 1240.5
          },
          "traditional_rental": {
            "roi": 2.29234,
            "cap_rate": 5.72545476462192,
            "rental_income": 4235.2
          }
        },
        "mashMeter": 31
      },
      {
        "id": 623416,
        "name": "Flamingo Lummus",
        "city": "Miami Beach",
        "state": "FL",
        "occupancy": 19,
        "total_listing": 1,
        "airbnb_listings": 322,
        "description": null,
        "single_home_value": 395000,
        "single_home_value_formatted": "$395,000",
        "investment_rentals": {
          "airbnb_rental": {
            "roi": -2.05932,
            "cap_rate": 2.635139240506329,
            "rental_income": 867.4
          },
          "traditional_rental": {
            "roi": 2.58527,
            "cap_rate": 15.824810126582278,
            "rental_income": 5209
          }
        },
        "mashMeter": 26
      }
    ]
  },
  "message": "City Overview fetched successfully"
}

GET/v1.1/client/neighborhood/:id/bar

Get Neighborhood Overview

Retrieves a neighborhood overview and investment analysis (MLS-defined areas). Includes description, scores, median price, and rental metrics.

Path parameters

Name
id
Type
integer
Description
Neighborhood ID.

Query parameters

Name
state
Type
string
Description
Two-letter state code for the neighborhood.

Request

GET

/v1.1/client/neighborhood/268201/bar

curl -G "https://api.mashvisor.com/v1.1/client/neighborhood/268201/bar?state=CA" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "status": "success",
  "content": {
    "id": "268201",
    "name": "Haight Ashbury",
    "city": "San Francisco",
    "county": "San Francisco",
    "state": "CA",
    "is_village": 0,
    "description": "Years ago, the Haight-Ashbury of San Francisco scene had a long-gone '60s and ‘70s hippie culture.  However, over time the Haight has changed.  But save for a few hippie memorabilia, today the Haight has a whole new vibe.  Although there are some fragments of flower-power, incense-burning, acid-dropping, peace-and-love-vibing era that can be purchased at smoke shops along the neighborhood, today the neighborhood is different. With exclusive boutiques, high-end vintage-clothing shops, second-hand stores, Internet cafés and hip restaurants having all settled in, this reinvented area stands out as one of San Francisco's commercial centers.  \r\n\r\nWhat makes the Haight unique is its just-rolled-out-of-bed vibe during the day, which provides a perfect opportunity for lazing around in cafés and bookstores.  Weekends can get quite crowded with shoppers and brunch seekers during the day and club-goers at night. Neo-punks, club kids, fashionistas, tourists and neighborhood locals also fit in here, whether they have come to get a new piercing, grab a burrito or just enjoy some fun people-watching from a café.  But there are two distinct areas of the Haight: The Upper Haight, which stretches from Stanyan to Masonic, which is known as the shopping zone, though it deteriorates a bit where it stretches toward Golden Gate Park. While, the Lower Haight, roughly Divisidero to Webster is a more diverse neighborhood with a stony feel. While it has been an alternate nightlife hub for years, the Lower Haight has become a main attraction for DJs and ravers with an attraction to dance-music and clubs.",
    "image": "https://9ac82074a42d61a93c2a-4910baab8d3df1a59178432e0b86512c.ssl.cf5.rackcdn.com",
    "latitude": 37.768094,
    "longitude": -122.448285,
    "walkscore": 96,
    "transitscore": 78,
    "bikescore": 74,
    "num_of_properties": 49,
    "num_of_airbnb_properties": 272,
    "num_of_traditional_properties": 4,
    "median_price": 1247000,
    "price_per_sqft": 1040.67,
    "mashMeter": 16,
    "mashMeterStars": 1.5,
    "avg_occupancy": 27.3934,
    "average_sold_price": 1523390,
    "average_days_on_market": 8,
    "number_of_sold_properties_last_month": 0,
    "number_of_sold_properties_last_year": 48,
    "sale_price_trends_last_1_year": 1535000,
    "sale_price_trends_last_3_years": 969305,
    "sale_price_trends_last_5_years": 990405,
    "strategy": "traditional",
    "airbnb_rental": {
      "roi": -0.14890646189451218,
      "cap_rate": 2.555316760224539,
      "rental_income": 2655.4,
      "rental_income_change": "down",
      "rental_income_change_percentage": -33.089288224910305,
      "night_price": 88.51333333333334,
      "occupancy": 27.3934,
      "occupancy_change": "down",
      "occupancy_change_percentage": -35.173591348890156,
      "price_change": "up",
      "price_change_percentage": 6.117163944433129,
      "insights": {
        "bedrooms": {
          "slope": -0.056435358228246406,
          "RSquare": 0.1590580989337962
        },
        "price": {
          "slope": -0.0001509847334722372,
          "RSquare": 0.14903142461633823
        },
        "stars_rate": {
          "slope": -1,
          "RSquare": -1
        },
        "bathrooms": {
          "slope": -0.09112747723620784,
          "RSquare": 0.12463502522414383
        },
        "beds": {
          "slope": -0.03654657942054976,
          "RSquare": 0.10927351943713126
        },
        "reviews_count": {
          "slope": 0.00040215289866135775,
          "RSquare": 0.15020938649904492
        }
      }
    },
    "traditional_rental": {
      "roi": 0.3293299227952957,
      "cap_rate": 4.431242983159583,
      "rental_income": 4604.8,
      "rental_income_change": "up",
      "rental_income_change_percentage": 3.2744236117340986,
      "night_price": 153.49333333333334,
      "occupancy": 96.2,
      "occupancy_change": null
    }
  },
  "message": "Neighborhood bar fetched successfully"
}

GET/v1.1/client/neighborhood/:id/schools

Get Neighborhood Schools

Retrieves the list of schools serving a specific neighborhood (name, location, type, grade levels, rating).

Path parameters

Name
id
Type
integer
Description
Neighborhood ID.

Query parameters

Name
state
Type
string
Description
Two-letter state code for the neighborhood.

Request

GET

/v1.1/client/neighborhood/123706/schools

curl -G "https://api.mashvisor.com/v1.1/client/neighborhood/123706/schools?state=FL" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "status": "success",
  "content": [
    {
      "state": "FL",
      "city": "Boca Raton",
      "county": "Palm Beach County",
      "neighborhood_id": 123706,
      "zipcode": "33433",
      "street": "7700 West Camino Real",
      "latitude": 26.342785,
      "longitude": -80.154884,
      "name": "Salt Academy",
      "school_summary": "Salt Academy, a private school located in Boca Raton, FL, serves grades K-11.",
      "type": "private",
      "level_codes": "e,m,h",
      "level": "KG,1,2,3,4,5,6,7,8,9,10,11",
      "phone": "(561) 235-5775",
      "overview_url": "https://www.greatschools.org/florida/boca-raton/19570-Salt-Academy/",
      "rating": 1
    },
    {
      "state": "FL",
      "city": "Boca Raton",
      "county": "Palm Beach County",
      "neighborhood_id": 123706,
      "zipcode": "33433",
      "street": "7000 West Palmetto Park Road",
      "name": "Palmetto Park High School",
      "school_summary": "Palmetto Park High School, a public school located in Boca Raton, FL, serves grades 7-12.",
      "type": "public",
      "level_codes": "m,h",
      "level": "7,8,9,10,11,12",
      "phone": "(561) 835-5498",
      "website": "https://palmettoparkhighschool.com/",
      "overview_url": "https://www.greatschools.org/florida/boca-raton/20348-Palmetto-Park-High-School/",
      "rating": 1
    }
  ]
}