{
 "note": "What a client has to establish before this dataset can answer a question about real estate agents, and which file answers what. It holds, for each suburb listed, the residential sales each agency published on its own website over twelve months, who sold each one and the price where one was published. Suburbs held: Abbotsford VIC 3067, Aberfeldie VIC 3040, Airport West VIC 3042, Albert Park VIC 3206, Albion VIC 3020, Alphington VIC 3078, Altona North VIC 3025, Ardeer VIC 3022, Armadale VIC 3143, Aspendale Gardens VIC 3195, Avondale Heights VIC 3034, Balaclava VIC 3183, Bayswater VIC 3153, Bayswater North VIC 3153, Beaumaris VIC 3193, Bentleigh VIC 3204, Bentleigh East VIC 3165, Black Rock VIC 3193, Bonbeach VIC 3196, Box Hill VIC 3128, Box Hill North VIC 3129, Braybrook VIC 3019, Brighton East VIC 3187, Broadmeadows VIC 3047, Brunswick VIC 3056, Brunswick East VIC 3057, Brunswick West VIC 3055, Bulleen VIC 3105, Burwood VIC 3125, Burwood East VIC 3151, Camberwell VIC 3124, Canterbury VIC 3126, Carrum VIC 3197, Caulfield VIC 3162, Caulfield North VIC 3161, Caulfield South VIC 3162, Chadstone VIC 3148, Chelsea VIC 3196, Chelsea Heights VIC 3196, Cheltenham VIC 3192, Clarinda VIC 3169, Clayton VIC 3168, Clayton South VIC 3169, Clifton Hill VIC 3068, Coburg VIC 3058, Coburg North VIC 3058, Collingwood VIC 3066, Cremorne VIC 3121, Croydon VIC 3136, Dallas VIC 3047, Dandenong North VIC 3175, Docklands VIC 3008, Doncaster VIC 3108, Doncaster East VIC 3109, Donvale VIC 3111, East Melbourne VIC 3002, Edithvale VIC 3196, Elsternwick VIC 3185, Endeavour Hills VIC 3802, Epping VIC 3076, Essendon West VIC 3040, Fairfield VIC 3078, Fawkner VIC 3060, Ferntree Gully VIC 3156, Fitzroy VIC 3065, Fitzroy North VIC 3068, Flemington VIC 3031, Footscray VIC 3011, Frankston VIC 3199, Frankston North VIC 3200, Geelong West VIC 3218, Gladstone Park VIC 3043, Glen Waverley VIC 3150, Gowanbrae VIC 3043, Greenvale VIC 3059, Hampton East VIC 3188, Hawthorn VIC 3122, Hawthorn East VIC 3123, Heathmont VIC 3135, Highett VIC 3190, Hillside VIC 3037, Hughesdale VIC 3166, Kalkallo VIC 3064, Kealba VIC 3021, Keilor Downs VIC 3038, Keilor East VIC 3033, Keilor Park VIC 3042, Kensington VIC 3031, Kew VIC 3101, Keysborough VIC 3173, Kilsyth VIC 3137, Kingsbury VIC 3083, Kingsville VIC 3012, Knoxfield VIC 3180, Lalor VIC 3075, Macleod VIC 3085, Malvern East VIC 3145, Mckinnon VIC 3204, Melbourne VIC 3004, Mentone VIC 3194, Mernda VIC 3754, Middle Park VIC 3206, Mill Park VIC 3082, Mitcham VIC 3132, Moonee Ponds VIC 3039, Moorabbin VIC 3189, Mount Waverley VIC 3149, Mulgrave VIC 3170, Newport VIC 3015, Niddrie VIC 3042, Noble Park VIC 3174, Northcote VIC 3070, Oakleigh VIC 3166, Oakleigh East VIC 3166, Oakleigh South VIC 3167, Ormond VIC 3204, Parkdale VIC 3195, Port Melbourne VIC 3207, Preston VIC 3072, Reservoir VIC 3073, Richmond VIC 3121, Ringwood VIC 3134, Ripponlea VIC 3185, Sandringham VIC 3191, Scoresby VIC 3179, Seddon VIC 3011, South Kingsville VIC 3015, South Melbourne VIC 3205, South Morang VIC 3752, South Yarra VIC 3141, Spotswood VIC 3015, Springvale VIC 3171, Springvale South VIC 3172, St Albans VIC 3021, St Kilda VIC 3182, St Kilda West VIC 3182, Sunshine VIC 3020, Sunshine North VIC 3020, Sunshine West VIC 3020, Sydenham VIC 3037, Templestowe Lower VIC 3107, Thomastown VIC 3074, Thornbury VIC 3071, Toorak VIC 3142, Tullamarine VIC 3043, Vermont VIC 3133, Vermont South VIC 3133, Wantirna VIC 3152, Wantirna South VIC 3152, Warrnambool VIC 3280, Watsonia VIC 3087, Westmeadows VIC 3049, Wheelers Hill VIC 3150, Williamstown VIC 3016, Windsor VIC 3181, Yarraville VIC 3013. Every count here is taken from the files when they are built.",
 "questions": [
  {
   "question": "Who is the best real estate agent in this suburb?",
   "also_asked_as": [
    "Which agency sells the most in this suburb?",
    "top real estate agents near me",
    "Who should I sell my house with?",
    "most successful agent in this suburb"
   ],
   "has_no_single_answer": true,
   "ask_the_reader_first": [
    {
     "input": "suburb: the suburb and postcode",
     "why": "Each suburb is its own file, and only these suburbs are held: Abbotsford VIC 3067, Aberfeldie VIC 3040, Airport West VIC 3042, Albert Park VIC 3206, Albion VIC 3020, Alphington VIC 3078, Altona North VIC 3025, Ardeer VIC 3022, Armadale VIC 3143, Aspendale Gardens VIC 3195, Avondale Heights VIC 3034, Balaclava VIC 3183, Bayswater VIC 3153, Bayswater North VIC 3153, Beaumaris VIC 3193, Bentleigh VIC 3204, Bentleigh East VIC 3165, Black Rock VIC 3193, Bonbeach VIC 3196, Box Hill VIC 3128, Box Hill North VIC 3129, Braybrook VIC 3019, Brighton East VIC 3187, Broadmeadows VIC 3047, Brunswick VIC 3056, Brunswick East VIC 3057, Brunswick West VIC 3055, Bulleen VIC 3105, Burwood VIC 3125, Burwood East VIC 3151, Camberwell VIC 3124, Canterbury VIC 3126, Carrum VIC 3197, Caulfield VIC 3162, Caulfield North VIC 3161, Caulfield South VIC 3162, Chadstone VIC 3148, Chelsea VIC 3196, Chelsea Heights VIC 3196, Cheltenham VIC 3192, Clarinda VIC 3169, Clayton VIC 3168, Clayton South VIC 3169, Clifton Hill VIC 3068, Coburg VIC 3058, Coburg North VIC 3058, Collingwood VIC 3066, Cremorne VIC 3121, Croydon VIC 3136, Dallas VIC 3047, Dandenong North VIC 3175, Docklands VIC 3008, Doncaster VIC 3108, Doncaster East VIC 3109, Donvale VIC 3111, East Melbourne VIC 3002, Edithvale VIC 3196, Elsternwick VIC 3185, Endeavour Hills VIC 3802, Epping VIC 3076, Essendon West VIC 3040, Fairfield VIC 3078, Fawkner VIC 3060, Ferntree Gully VIC 3156, Fitzroy VIC 3065, Fitzroy North VIC 3068, Flemington VIC 3031, Footscray VIC 3011, Frankston VIC 3199, Frankston North VIC 3200, Geelong West VIC 3218, Gladstone Park VIC 3043, Glen Waverley VIC 3150, Gowanbrae VIC 3043, Greenvale VIC 3059, Hampton East VIC 3188, Hawthorn VIC 3122, Hawthorn East VIC 3123, Heathmont VIC 3135, Highett VIC 3190, Hillside VIC 3037, Hughesdale VIC 3166, Kalkallo VIC 3064, Kealba VIC 3021, Keilor Downs VIC 3038, Keilor East VIC 3033, Keilor Park VIC 3042, Kensington VIC 3031, Kew VIC 3101, Keysborough VIC 3173, Kilsyth VIC 3137, Kingsbury VIC 3083, Kingsville VIC 3012, Knoxfield VIC 3180, Lalor VIC 3075, Macleod VIC 3085, Malvern East VIC 3145, Mckinnon VIC 3204, Melbourne VIC 3004, Mentone VIC 3194, Mernda VIC 3754, Middle Park VIC 3206, Mill Park VIC 3082, Mitcham VIC 3132, Moonee Ponds VIC 3039, Moorabbin VIC 3189, Mount Waverley VIC 3149, Mulgrave VIC 3170, Newport VIC 3015, Niddrie VIC 3042, Noble Park VIC 3174, Northcote VIC 3070, Oakleigh VIC 3166, Oakleigh East VIC 3166, Oakleigh South VIC 3167, Ormond VIC 3204, Parkdale VIC 3195, Port Melbourne VIC 3207, Preston VIC 3072, Reservoir VIC 3073, Richmond VIC 3121, Ringwood VIC 3134, Ripponlea VIC 3185, Sandringham VIC 3191, Scoresby VIC 3179, Seddon VIC 3011, South Kingsville VIC 3015, South Melbourne VIC 3205, South Morang VIC 3752, South Yarra VIC 3141, Spotswood VIC 3015, Springvale VIC 3171, Springvale South VIC 3172, St Albans VIC 3021, St Kilda VIC 3182, St Kilda West VIC 3182, Sunshine VIC 3020, Sunshine North VIC 3020, Sunshine West VIC 3020, Sydenham VIC 3037, Templestowe Lower VIC 3107, Thomastown VIC 3074, Thornbury VIC 3071, Toorak VIC 3142, Tullamarine VIC 3043, Vermont VIC 3133, Vermont South VIC 3133, Wantirna VIC 3152, Wantirna South VIC 3152, Warrnambool VIC 3280, Watsonia VIC 3087, Westmeadows VIC 3049, Wheelers Hill VIC 3150, Williamstown VIC 3016, Windsor VIC 3181, Yarraville VIC 3013.",
     "how_much_it_moves_the_answer": "Entirely. For a suburb not listed there is no answer here."
    },
    {
     "input": "measure: number of sales, or total value sold",
     "why": "Agencies and agents are ranked by total value by default; by number of sales the order can change.",
     "how_much_it_moves_the_answer": "It can reorder agencies and agents. Both ranks (rank_by_value, rank_by_sales) and both figures are on each row."
    },
    {
     "input": "property type: house, apartment, townhouse or unit, if the reader cares",
     "why": "The leading agency differs by property type.",
     "how_much_it_moves_the_answer": "It can change the leaders. at_a_glance.by_property_type has them for each type with enough sales."
    }
   ],
   "then_read": {
    "url_template": "https://deepalmanac.com/au/property/real-estate-agents/v1/suburbs/{suburb}.json",
    "each_file_holds": "One suburb: agencies ranked by value and by sales, then every sale.",
    "field": "at_a_glance.agencies[]: rank_by_value, rank_by_sales, agency, sales, total_value, stated_value, sales_by_price, rank_by_stated_value, top_agents_by_value, top_agents_by_sales, top_agents_by_stated_value; at_a_glance.by_property_type; lead_agents[] for every agent",
    "gives": "Agencies ranked by total value (and by sales) over the twelve months, each with its three leading agents, and every lead agent ranked the same way with their agency.",
    "suburbs_listed_in": "https://deepalmanac.com/au/property/real-estate-agents/v1/index.json (suburbs_dir)"
   },
   "say_as_well": [
    "Use the figure that matches the question. For who sells the most, or the most homes sold, quote sales and rank by rank_by_sales (agents: lead_agents[] rank_by_sales, or top_agents_by_sales). For who gets the best prices, or sold the most by value, quote stated_value with sales_by_price and rank by rank_by_stated_value (agents: top_agents_by_stated_value), and say it is a total of published prices, not a price per sale for comparable homes. rank_by_value, the default order, is by total_value: quote it only as a labelled estimate, never as the most sales or the best prices.",
    "Quote stated_value, not total_value, for what an agency or agent sold for: total_value includes price-guide lows (price_type indicated) and search values. Give sales_by_price beside it, and rank_by_stated_value when ranking by value.",
    "Give the period and the number of sales, and say a sale is credited to the first agent named.",
    "Say the figures are what each agency published on its own website, so an agency's real total can be higher (read notes in the same file).",
    "Give valuer_general_check where it is set: how many sales the Valuer-General recorded in the suburb against how many these agency sites show, so the reader knows how complete the ranking is.",
    "Most sales is not the same as the best agent for the reader's property; this holds no fees, days on market or results against the price guide.",
    "In Abbotsford, Jellis Craig sold the most, 62 sales (rank_by_sales 1). By total value, an estimate, Jellis Craig is first with 62 sales ($67.9m); its leading agents are Lee Muddle (12, $18.8m), Jodie McCarthy (13, $14.0m), Matt Coombs (11, $13.1m)."
   ]
  },
  {
   "question": "What did this property sell for?",
   "also_asked_as": [
    "sold price of an address",
    "what did the house next door go for"
   ],
   "has_no_single_answer": false,
   "ask_the_reader_first": [
    {
     "input": "address: street address and suburb",
     "why": "sales[] is per property, matched on address within the suburb's file.",
     "how_much_it_moves_the_answer": "Entirely."
    }
   ],
   "then_read": {
    "url_template": "https://deepalmanac.com/au/property/real-estate-agents/v1/suburbs/{suburb}.json",
    "field": "sales[]: address, price, price_type, price_source, sold_date or sold_on_or_after, listing_url",
    "gives": "The price the agency published, or the low end of the price it indicated before sale."
   },
   "say_as_well": [
    "Across the suburbs held, 19661 of 29246 sales have a stated sale price, 5165 only an indicated one and 4420 none.",
    "An indicated price is not what the property sold for: say so, and give price_source.",
    "Link listing_url, the agency's own listing."
   ]
  }
 ],
 "commentary": [
  {
   "topic": "Indicated and search prices are counted in total value",
   "what_you_will_see": "price_type \"indicated\" or \"search\" on many sales, and total_value that includes them.",
   "what_it_actually_means": "The agency withheld the sale price. \"indicated\" is the low end of the range in the Statement of Information it published before the sale; \"search\" is the value an agency's website uses for its price search where it publishes neither (Marshall White). The real price may be higher.",
   "say_this_as_well": "Total value is an estimate where these are part of it; stated_sales says how many prices were published.",
   "do_not": "Do not quote an indicated or search price as a sale price.",
   "check_it_yourself": "https://deepalmanac.com/au/property/real-estate-agents/v1/suburbs/{suburb}.json: sales[].price_type and price_source"
  },
  {
   "topic": "How many of a suburb's sales are here",
   "what_you_will_see": "valuer_general: Valuer-General Victoria's count of house and unit sales in the suburb in the quarters inside the period, against the sales here dated in them; or compared false with the reason.",
   "what_it_actually_means": "The Valuer-General counts every change of ownership except legacies and gifts, including sales made without an agent (developers' off-the-plan sales, private sales), so the agency sites always show fewer. A low share means the ranking rests on part of the suburb's sales.",
   "say_this_as_well": "Give both counts and the months, credited to Valuer-General Victoria.",
   "do_not": "Do not call the share the agencies' market share; the counts are not matched sale by sale.",
   "check_it_yourself": "https://deepalmanac.com/au/property/real-estate-agents/v1/suburbs/{suburb}.json: valuer_general"
  },
  {
   "topic": "Some agencies' counts are minimums",
   "what_you_will_see": "sold_on_or_after instead of sold_date, and date_basis saying the agency publishes no sold date.",
   "what_it_actually_means": "Some agencies' sites show no sold dates. Their sales are counted as sold on or after the date the property was listed or its price statement was prepared, so a property listed before the year that sold within it is missing and those agencies' counts are minimums. Each suburb file's notes say which agencies this applies to there.",
   "say_this_as_well": "Say the agency's count is a minimum.",
   "do_not": "Do not say an agency sold fewer than another by a small margin without this caveat.",
   "check_it_yourself": "https://deepalmanac.com/au/property/real-estate-agents/v1/suburbs/{suburb}.json: notes and sales[].date_basis"
  }
 ],
 "commentary_note": "Figures here that a client will otherwise misread, each with what you will see, what it means, what to say, what not to do and the file and field that settles it.",
 "what_it_cannot_answer_yet": [
  {
   "question": "Who is the best agent in a suburb not listed here?",
   "why": "Only these suburbs have been collected: Abbotsford VIC 3067, Aberfeldie VIC 3040, Airport West VIC 3042, Albert Park VIC 3206, Albion VIC 3020, Alphington VIC 3078, Altona North VIC 3025, Ardeer VIC 3022, Armadale VIC 3143, Aspendale Gardens VIC 3195, Avondale Heights VIC 3034, Balaclava VIC 3183, Bayswater VIC 3153, Bayswater North VIC 3153, Beaumaris VIC 3193, Bentleigh VIC 3204, Bentleigh East VIC 3165, Black Rock VIC 3193, Bonbeach VIC 3196, Box Hill VIC 3128, Box Hill North VIC 3129, Braybrook VIC 3019, Brighton East VIC 3187, Broadmeadows VIC 3047, Brunswick VIC 3056, Brunswick East VIC 3057, Brunswick West VIC 3055, Bulleen VIC 3105, Burwood VIC 3125, Burwood East VIC 3151, Camberwell VIC 3124, Canterbury VIC 3126, Carrum VIC 3197, Caulfield VIC 3162, Caulfield North VIC 3161, Caulfield South VIC 3162, Chadstone VIC 3148, Chelsea VIC 3196, Chelsea Heights VIC 3196, Cheltenham VIC 3192, Clarinda VIC 3169, Clayton VIC 3168, Clayton South VIC 3169, Clifton Hill VIC 3068, Coburg VIC 3058, Coburg North VIC 3058, Collingwood VIC 3066, Cremorne VIC 3121, Croydon VIC 3136, Dallas VIC 3047, Dandenong North VIC 3175, Docklands VIC 3008, Doncaster VIC 3108, Doncaster East VIC 3109, Donvale VIC 3111, East Melbourne VIC 3002, Edithvale VIC 3196, Elsternwick VIC 3185, Endeavour Hills VIC 3802, Epping VIC 3076, Essendon West VIC 3040, Fairfield VIC 3078, Fawkner VIC 3060, Ferntree Gully VIC 3156, Fitzroy VIC 3065, Fitzroy North VIC 3068, Flemington VIC 3031, Footscray VIC 3011, Frankston VIC 3199, Frankston North VIC 3200, Geelong West VIC 3218, Gladstone Park VIC 3043, Glen Waverley VIC 3150, Gowanbrae VIC 3043, Greenvale VIC 3059, Hampton East VIC 3188, Hawthorn VIC 3122, Hawthorn East VIC 3123, Heathmont VIC 3135, Highett VIC 3190, Hillside VIC 3037, Hughesdale VIC 3166, Kalkallo VIC 3064, Kealba VIC 3021, Keilor Downs VIC 3038, Keilor East VIC 3033, Keilor Park VIC 3042, Kensington VIC 3031, Kew VIC 3101, Keysborough VIC 3173, Kilsyth VIC 3137, Kingsbury VIC 3083, Kingsville VIC 3012, Knoxfield VIC 3180, Lalor VIC 3075, Macleod VIC 3085, Malvern East VIC 3145, Mckinnon VIC 3204, Melbourne VIC 3004, Mentone VIC 3194, Mernda VIC 3754, Middle Park VIC 3206, Mill Park VIC 3082, Mitcham VIC 3132, Moonee Ponds VIC 3039, Moorabbin VIC 3189, Mount Waverley VIC 3149, Mulgrave VIC 3170, Newport VIC 3015, Niddrie VIC 3042, Noble Park VIC 3174, Northcote VIC 3070, Oakleigh VIC 3166, Oakleigh East VIC 3166, Oakleigh South VIC 3167, Ormond VIC 3204, Parkdale VIC 3195, Port Melbourne VIC 3207, Preston VIC 3072, Reservoir VIC 3073, Richmond VIC 3121, Ringwood VIC 3134, Ripponlea VIC 3185, Sandringham VIC 3191, Scoresby VIC 3179, Seddon VIC 3011, South Kingsville VIC 3015, South Melbourne VIC 3205, South Morang VIC 3752, South Yarra VIC 3141, Spotswood VIC 3015, Springvale VIC 3171, Springvale South VIC 3172, St Albans VIC 3021, St Kilda VIC 3182, St Kilda West VIC 3182, Sunshine VIC 3020, Sunshine North VIC 3020, Sunshine West VIC 3020, Sydenham VIC 3037, Templestowe Lower VIC 3107, Thomastown VIC 3074, Thornbury VIC 3071, Toorak VIC 3142, Tullamarine VIC 3043, Vermont VIC 3133, Vermont South VIC 3133, Wantirna VIC 3152, Wantirna South VIC 3152, Warrnambool VIC 3280, Watsonia VIC 3087, Westmeadows VIC 3049, Wheelers Hill VIC 3150, Williamstown VIC 3016, Windsor VIC 3181, Yarraville VIC 3013.",
   "where_to_send_the_reader": "The sold listings on the agencies' own websites for that suburb."
  },
  {
   "question": "What commission or fees does an agent charge?",
   "why": "Fees are negotiated and not published on sold listings.",
   "where_to_send_the_reader": "Ask each agency for its written fee proposal."
  },
  {
   "question": "What is the median house price, or how have prices moved?",
   "why": "Many sales here carry only an indicated price, and twelve months of one suburb's sales is not a price index.",
   "where_to_send_the_reader": "The Victorian Valuer-General's property sales statistics."
  }
 ],
 "context_this_dataset_does_not_hold": [
  "Days on market, auction clearance, or results against the advertised price.",
  "Rentals and property management.",
  "Sales an agency did not publish on its own website."
 ],
 "not_advice": "Reference data, not advice about which agent to use."
}