{
  "openapi": "3.0.1",
  "info": {
    "title": "Apartments.com API & Scraper — US Rentals + Walk Score",
    "description": "Apartments.com scraper and US rental data API. Search by location, ZIP, coordinates, address, URL or listing key; return rent, beds, baths, floor plans, property manager and contact details, amenities, pet policies, lease terms, walk scores, schools and reviews.",
    "version": "1.1",
    "x-build-id": "CtkZOinV2CDSxsXcm"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/sian.agency~apartments-com-property-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-sian.agency-apartments-com-property-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/sian.agency~apartments-com-property-scraper/runs": {
      "post": {
        "operationId": "runs-sync-sian.agency-apartments-com-property-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/sian.agency~apartments-com-property-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-sian.agency-apartments-com-property-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "searchMode": {
            "title": "🧭 Search Mode",
            "enum": [
              "byLocation",
              "byZip",
              "byCoordinates",
              "byUrl",
              "byPolygon",
              "byRegionId",
              "bulkLocations",
              "byListingKeys",
              "byListingUrl",
              "byAddress"
            ],
            "type": "string",
            "description": "How to find rental listings.\n\n• **byLocation** — free-text city/neighborhood (e.g. \"Brooklyn, NY\")\n• **byZip** — 5-digit US zip code (e.g. \"10001\")\n• **byCoordinates** — lat/lng + radius (miles)\n• **byUrl** — paste any apartments.com region or city URL\n• **bulkLocations** — batch dozens of locations in one run (PAID)\n• **byListingKeys** — enrich known listings directly by listing key or listing URL (PAID)\n• **byListingUrl** — NEW: look up ONE listing directly by its full apartments.com listing URL, no search needed\n• **byAddress** — NEW: look up ONE listing directly by its street address, no search needed\n• **byPolygon** — closed polygon ring of `lon lat` pairs\n• **byRegionId** — apartments.com geography ID (from its autocomplete: id + typeCode)",
            "default": "byLocation"
          },
          "maxResults": {
            "title": "📊 Max results per query",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Hard cap on listings returned per query. Each query pulls up to 500 listings in a single high-throughput page (500 is the upstream maximum per search — narrow the area for deeper coverage). FREE tier is always capped at 25 listings per run.",
            "default": 100
          },
          "location": {
            "title": "📍 Location  (used when Search Mode = byLocation)",
            "type": "string",
            "description": "Free-text US city or neighborhood. Examples:\n• \"Brooklyn, NY\"\n• \"Capitol Hill, Seattle\"\n• \"Austin, TX\"\n• \"Williamsburg\"\n\nThe API will fuzzy-match — your run summary will echo the matched location.",
            "default": "Brooklyn, NY"
          },
          "zip": {
            "title": "📮 Zip Code  (used when Search Mode = byZip)",
            "type": "string",
            "description": "5-digit US zip code (e.g. \"10001\", \"78704\")."
          },
          "latitude": {
            "title": "🗺️ Latitude  (used when Search Mode = byCoordinates)",
            "minimum": -90,
            "maximum": 90,
            "type": "number",
            "description": "Center latitude for a radial search."
          },
          "longitude": {
            "title": "🗺️ Longitude  (used when Search Mode = byCoordinates)",
            "minimum": -180,
            "maximum": 180,
            "type": "number",
            "description": "Center longitude for a radial search."
          },
          "radius": {
            "title": "📏 Radius (miles)",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "Search radius in miles around the lat/lng center (1-50).",
            "default": 5
          },
          "url": {
            "title": "🔗 Apartments.com URL  (used when Search Mode = byUrl)",
            "type": "string",
            "description": "Paste any apartments.com region, city, or neighborhood URL. Examples:\n• https://www.apartments.com/new-york-ny/\n• https://www.apartments.com/brooklyn-ny/\n• https://www.apartments.com/austin-tx/"
          },
          "polygon": {
            "title": "🔷 Polygon ring  (used when Search Mode = byPolygon)",
            "type": "string",
            "description": "Closed polygon as `lon lat, lon lat, …` (at least 4 points, lon first). First and last point must match (auto-closed if not).\n\nExample (central Austin, TX): `-97.78 30.35, -97.68 30.35, -97.68 30.22, -97.78 30.22, -97.78 30.35`"
          },
          "geographyId": {
            "title": "🗺 Geography ID  (used when Search Mode = byRegionId)",
            "type": "integer",
            "description": "apartments.com geography ID (e.g. 6062 = Austin, TX). Get it from apartments.com's location autocomplete: each suggestion carries `id` and `typeCode`."
          },
          "geographyType": {
            "title": "🗺 Geography type  (used when Search Mode = byRegionId)",
            "type": "integer",
            "description": "The suggestion's `typeCode` (city = 3, the default). Must match the geography ID's type or the search returns 0 results.",
            "default": 3
          },
          "locations": {
            "title": "📋 Bulk Locations  (PAID, bulkLocations mode)",
            "uniqueItems": true,
            "type": "array",
            "description": "Array of US location strings (one search per item). PAID tier only. Examples: [\"Brooklyn, NY\", \"Austin, TX\", \"Seattle, WA\"].",
            "items": {
              "type": "string"
            }
          },
          "listingKeys": {
            "title": "🔑 Listing Keys / URLs  (used when Search Mode = byListingKeys, PAID)",
            "uniqueItems": true,
            "type": "array",
            "description": "Known apartments.com listings to enrich directly — bare listing keys (e.g. \"7zg13yw\", the `listingKey` field on every search-result row) or full apartments.com listing URLs (e.g. \"https://www.apartments.com/the-eugene-new-york-ny/0smfmv0/\"). Combine with the enrichment / reviews / fees toggles below — if none is selected, reviews + fees are fetched by default. PAID tier only.",
            "items": {
              "type": "string"
            }
          },
          "listingUrl": {
            "title": "🔗 Listing URL  (used when Search Mode = byListingUrl)",
            "type": "string",
            "description": "Full apartments.com LISTING url (not a region/city url) — must end in the listing's key segment. Example: \"https://www.apartments.com/the-eugene-new-york-ny/0smfmv0/\". Resolved server-side, so any URL form apartments.com itself links to will work — you don't need to already know the internal listing key."
          },
          "address": {
            "title": "🏠 Street Address  (used when Search Mode = byAddress)",
            "type": "string",
            "description": "Full property street address — street + city + state, ZIP optional. Example: \"9 Homestead Pl, Jersey City, NJ\". apartments.com only knows properties it has an active listing for — unlisted single-family homes return no data (and no charge)."
          },
          "includeEnrichment": {
            "title": "⭐ Include enrichment bundle (PAID)",
            "type": "boolean",
            "description": "When ON, fetches the full enrichment bundle for each listing in parallel: details (description + amenities + fees + lease terms + photos), info (year built, unit count, story count), walk/transit/bike scores, schools, pet policy, rental costs, unit-level availabilities, a standalone amenities list, and the full photo gallery. 9 extra API calls per listing run in parallel. Adds one enrichment-fetched charge per listing where at least one enrichment fetch succeeded. Disabled on FREE tier.",
            "default": false
          },
          "includeReviews": {
            "title": "💬 Include renter reviews (PAID)",
            "type": "boolean",
            "description": "When ON, fetches renter reviews for each listing: title, full review text, 1–5 rating, submission date, owner flag, and helpful-vote count, plus the listing's total review count. 1 extra API call per listing. Adds one enrichment-fetched charge per listing that has at least one review — listings without reviews are never charged. Disabled on FREE tier.",
            "default": false
          },
          "includeFees": {
            "title": "💵 Include fees, management & office hours (PAID)",
            "type": "boolean",
            "description": "When ON, fetches the full fee/expense schedule for each listing (application, admin, pet, parking, and storage fees with amounts, refundability, and recurrence), the property-management company (name + phone), and leasing-office hours. 3 extra API calls per listing run in parallel, charged as one enrichment-fetched event per listing where data was found. Disabled on FREE tier.",
            "default": false
          },
          "includeSimilar": {
            "title": "🏘 Include similar listings (PAID, NEW)",
            "type": "boolean",
            "description": "When ON, fetches apartments.com's own comparable-listings recommendations for each listing (matched by neighborhood, price band, and bedroom count) — up to a handful of lightweight comps per listing. 1 extra API call per listing. Adds one enrichment-fetched charge per listing that actually has comps — listings with zero comps are never charged. Disabled on FREE tier.",
            "default": false
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}