{
 "openapi": "3.1.0",
 "info": {
  "title": "Deep Almanac: Australian real estate agents by suburb",
  "version": "1.0.0",
  "summary": "The real estate agencies and agents with the most residential sales in a suburb over twelve months, from each agency's own sold listings.",
  "description": "For each suburb held, the residential sales each agency published on its own website over twelve months: address, agency, office, lead agent and co-agents, sold date (or the listing date where the agency shows none), and the sale price the agency published or, where it withheld it, the low end of the price indicated before sale. Agencies and agents are ranked by total value, and by number of sales. Suburbs: 156.\n\nEvery file is static JSON; no authentication, CORS open. This is reference data, not advice about which agent to use.",
  "termsOfService": "https://deepalmanac.com/terms",
  "contact": {
   "name": "Deep Almanac",
   "url": "https://deepalmanac.com"
  },
  "license": {
   "name": "Deep Almanac's own work CC BY 4.0; source data under its own terms, listed in licences in each index.json",
   "url": "https://deepalmanac.com/terms#data-licences"
  }
 },
 "servers": [
  {
   "url": "https://deepalmanac.com"
  }
 ],
 "security": [],
 "tags": [
  {
   "name": "real-estate-agents",
   "description": "Australian real estate agents by suburb",
   "externalDocs": {
    "description": "Page",
    "url": "https://deepalmanac.com/au/property/real-estate-agents/"
   }
  }
 ],
 "paths": {
  "/au/property/real-estate-agents/v1/index.json": {
   "get": {
    "tags": [
     "real-estate-agents"
    ],
    "operationId": "getRealEstateAgentsIndex",
    "summary": "Dataset index",
    "description": "The dataset's files, timestamps and every suburb held, with templates for its page and JSON URL.",
    "responses": {
     "200": {
      "description": "Dataset index.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "dataset": {
           "type": "string",
           "description": "Dataset name."
          },
          "page": {
           "type": "string",
           "description": "Human-readable page for the dataset.",
           "format": "uri"
          },
          "start_here": {
           "type": [
            "object",
            "null"
           ],
           "description": "The small file that answers most questions here: answer_file (a URL template), inputs (how to fill it), example (a filled-in URL) and sometimes also (the next file for a common variant).",
           "properties": {
            "answer_file": {
             "type": "string",
             "description": "URL template of the answer file."
            },
            "inputs": {
             "type": "string",
             "description": "What each placeholder takes."
            },
            "example": {
             "type": "string",
             "description": "A filled-in answer file URL.",
             "format": "uri"
            },
            "also": {
             "type": "string",
             "description": "Another file for a common variant of the question."
            },
            "lookup": {
             "type": "string",
             "description": "Where present: a /v1/lookup URL that takes the reader's own numbers, applies the bucket rules and redirects to the answer file.",
             "format": "uri"
            },
            "compare": {
             "type": "string",
             "description": "Where present: a /v1/compare URL that ranks every rate at the reader's exact amount and answers with JSON directly.",
             "format": "uri"
            }
           }
          },
          "generated_at": {
           "type": "string",
           "description": "When this index was written, UTC, YYYY-MM-DDTHH:MM:SSZ.",
           "format": "date-time",
           "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
          },
          "fetched_at": {
           "type": "string",
           "description": "When the source was last fetched, UTC, YYYY-MM-DDTHH:MM:SSZ.",
           "format": "date-time",
           "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
          },
          "data_as_of": {
           "type": "string",
           "description": "How current the data is: a date (YYYY-MM-DD) or a UTC timestamp (YYYY-MM-DDTHH:MM:SSZ); data_as_of_basis says what it means here.",
           "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}Z)?$"
          },
          "data_as_of_basis": {
           "type": "string",
           "description": "One sentence saying what data_as_of means for this dataset."
          },
          "source": {
           "type": "string",
           "description": "Data source statement."
          },
          "licence_note": {
           "type": "string",
           "description": "Terms of reuse and the not-advice note."
          },
          "licences": {
           "type": "array",
           "description": "What may be reused and on what terms, layer by layer: each layer's source, the fields it covers, its licence and the attribution it asks for. The last layer is Deep Almanac's own work (CC BY 4.0), covering every field no other layer names. Reusing a field means meeting the terms of the layer that covers it.",
           "items": {
            "type": "object",
            "required": [
             "layer",
             "covers",
             "licence",
             "licence_url",
             "attribution"
            ],
            "properties": {
             "layer": {
              "type": "string",
              "description": "The source."
             },
             "covers": {
              "type": "string",
              "description": "The fields it covers."
             },
             "licence": {
              "type": "string",
              "description": "Its licence, or why there is none."
             },
             "licence_url": {
              "type": [
               "string",
               "null"
              ],
              "format": "uri",
              "description": "The licence's own page, where it has one."
             },
             "attribution": {
              "type": "string",
              "description": "The credit the layer asks for."
             }
            }
           }
          },
          "questions": {
           "type": "string",
           "description": "This dataset's questions.json: what to ask the reader first and which file answers each.",
           "format": "uri"
          },
          "openapi": {
           "type": "string",
           "description": "This dataset's OpenAPI document.",
           "format": "uri"
          },
          "status": {
           "type": "string",
           "description": "https://deepalmanac.com/status.json: when every dataset was last fetched and when it counts as overdue.",
           "format": "uri"
          },
          "llms": {
           "type": "string",
           "description": "https://deepalmanac.com/llms.txt: the site's guide for language models.",
           "format": "uri"
          },
          "files": {
           "type": "array",
           "description": "Every top-level file this dataset publishes, as absolute URLs.",
           "items": {
            "type": "string",
            "format": "uri"
           }
          },
          "file_guide": {
           "type": "array",
           "description": "What each of those files holds, in the same order.",
           "items": {
            "type": "object",
            "properties": {
             "file": {
              "type": "string"
             },
             "url": {
              "type": "string",
              "format": "uri"
             },
             "description": {
              "type": "string"
             }
            }
           }
          },
          "suburb_count": {
           "type": "integer"
          },
          "sale_count": {
           "type": "integer"
          },
          "suburbs_dir": {
           "type": "object",
           "description": "Every suburb held, with its slug, period, sales and agencies; url_template and page_template give its JSON and page."
          }
         },
         "required": [
          "dataset",
          "page",
          "start_here",
          "generated_at",
          "fetched_at",
          "data_as_of",
          "data_as_of_basis",
          "source",
          "licence_note",
          "licences",
          "questions",
          "openapi",
          "status",
          "llms",
          "files",
          "suburbs_dir"
         ]
        }
       }
      }
     },
     "404": {
      "description": "Not published, or the path is wrong; the body is JSON naming the dataset's files."
     }
    }
   }
  },
  "/au/property/real-estate-agents/v1/questions.json": {
   "get": {
    "tags": [
     "real-estate-agents"
    ],
    "operationId": "getRealEstateAgentsQuestions",
    "summary": "What to ask a reader before answering",
    "description": "The questions readers ask, the inputs to collect first, which file and field answers each, what is most often misread (indicated prices, counts that are minimums) and what this dataset does not hold. Read this first.",
    "responses": {
     "200": {
      "description": "What to ask a reader before answering.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Not published, or the path is wrong; the body is JSON naming the dataset's files."
     }
    }
   }
  },
  "/au/property/real-estate-agents/v1/suburbs/{suburb}.json": {
   "get": {
    "tags": [
     "real-estate-agents"
    ],
    "operationId": "getRealEstateAgentsSuburb",
    "summary": "One suburb",
    "description": "at_a_glance ranks the agencies by total value and by sales, with their three leading agents each way; agencies has every agent's count and value within each agency; lead_agents ranks every named lead agent in the suburb, and all_listed_agents ranks every agent named on a sale, each sale counting in full for each of them; agent_pages maps agency and agent to the agent's page on the agency's own website, where one was found; sales has every sale with its price, price type, date and the agency's listing URL; notes says how it was counted.",
    "responses": {
     "200": {
      "description": "One suburb.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Not published, or the path is wrong; the body is JSON naming the dataset's files."
     }
    },
    "parameters": [
     {
      "name": "suburb",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "suburb-state-postcode, lower case, e.g. abbotsford-vic-3067; listed in index.json."
     }
    ]
   }
  },
  "/au/property/real-estate-agents/v1/openapi.json": {
   "get": {
    "tags": [
     "real-estate-agents"
    ],
    "operationId": "getRealEstateAgentsOpenApi",
    "summary": "This OpenAPI document",
    "description": "OpenAPI 3.1 description of this dataset (https://deepalmanac.com/openapi.json lists every dataset's document).",
    "responses": {
     "200": {
      "description": "This OpenAPI document.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Not published, or the path is wrong; the body is JSON naming the dataset's files."
     }
    }
   }
  }
 }
}