{"openapi":"3.1.0","info":{"title":"Clarity Property Investments agent API","version":"1.0.0","description":"UK buy-to-let location data for software agents: entry prices, rental yields by kind of home, price growth, tenant demand, crime and local facts for every ranked town, London borough and Scottish council area. England, Wales and Scotland; Northern Ireland is not covered.\n\nPaid per call in USDC on Base over x402 (HTTP 402): no account, no key. LS6 is answered free, in full, so the data can be judged before paying.\n\nEvery answer carries asOf: the day the dataset was built and, for each field, its source, grain and window. An absent field was not measured; absent is not zero.\n\nResearch, not regulated financial advice.","contact":{"email":"info@claritypropertyinvestments.com","url":"https://claritypropertyinvestments.com"},"license":{"name":"Figures contain public sector information licensed under the Open Government Licence v3.0; each answer states its attribution."}},"servers":[{"url":"https://claritypropertyinvestments.com"}],"paths":{"/api/v1/districts":{"get":{"operationId":"listDistricts","summary":"Every covered postcode district, the prices and payment details. Free.","responses":{"200":{"description":"The index."}}}},"/api/v1/districts/{district}":{"get":{"operationId":"getDistrict","summary":"One postcode district's full figures. $0.10 a call; LS6 free.","description":"Answers with every ranked place that contains the district (a few districts sit in two or three). A full postcode is answered as its district. Malformed or uncovered districts are refused before payment, free.","x-payment":{"protocol":"x402","version":2,"scheme":"exact","price":"$0.10","asset":"USDC","network":"eip155:8453","payTo":"0x407DCFDd5B583c07cBAdd2Ba5cFE907ac7988f77"},"parameters":[{"name":"district","in":"path","required":true,"schema":{"type":"string"},"example":"M14","description":"A postcode district (M14, SW1A, G12) or a full postcode (M14 5RX)."}],"responses":{"200":{"description":"The district's places and their figures.","content":{"application/json":{"schema":{"type":"object","properties":{"district":{"type":"string"},"locations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"localAuthority":{"type":["string","null"]},"entryPriceGbp":{"type":"number","description":"Median sold price of the place's cheapest postcode district, GBP. Source: HM Land Registry Price Paid Data, standard sales only (category B excluded). Scotland: the council's lower-quartile price, Registers of Scotland. Grain: place. Window: The trailing twelve months of registered sales when the dataset was built. Scotland: the latest whole calendar year."},"grossYield":{"type":"object","description":"Gross yield, percent: twelve months of median rent over the median sold price of the same kind of home (propertyType). monthlyRentGbp is that rent. Source: ONS private rents (Broad Rental Market Area in Scotland) over HM Land Registry or Registers of Scotland prices. Grain: authority. Window: The latest ONS rent release and the same sales window as entryPriceGbp."},"nation":{"type":["string","null"],"enum":["england","wales","scotland",null],"description":"The nation the authority is in, which decides the purchase tax."},"buyToLetPurchaseTax":{"type":["object","null"],"description":"The tax on a buy-to-let at entryPriceGbp for a UK resident: SDLT with the 5% surcharge (England), LTT at the higher rates (Wales), or LBTT with the 8% Additional Dwelling Supplement (Scotland).","properties":{"taxName":{"type":"string"},"totalGbp":{"type":"number"},"atPriceGbp":{"type":"number"}}},"intelligence":{"type":"object","description":"Measured figures; any may be absent.","properties":{"population":{"description":"Resident population. Source: ONS population estimates. Grain: authority. Window: The latest published estimate."},"populationGrowthPct":{"description":"Annualised population growth, percent. Source: ONS population estimates. Grain: authority. Window: Across the latest published estimates."},"rentalDemandScore":{"description":"Tenant demand, 1 (low) to 10 (very high): a weighted percentile rank of employment density, five-year population growth and price-to-earnings, relative to every place covered. Source: Clarity, from ONS and NOMIS employment, population and earnings data. Grain: place. Window: As at the dataset build."},"netAdditionalDwellings":{"description":"Homes added in the year, net of demolitions and conversions. England only. Source: MHCLG Live Table 122. Grain: authority. Window: The latest financial year published."},"dwellingGrowthPer1000":{"description":"Net additional homes per 1,000 existing dwellings, smoothed over three years. England only. Source: MHCLG Live Table 122. Grain: authority. Window: The latest three financial years published."},"regenerationZone":{"description":"Whether the authority has won central government regeneration money or sits under a live development corporation. False is a claim, not a gap. Source: Levelling Up Fund rounds 1–3, Pride in Place phases 1–2, development corporations. Grain: authority. Window: Every round to date."},"regenerationProgrammeCount":{"description":"How many of the five tracked funding rounds the authority won, 0–5. Source: Levelling Up Fund rounds 1–3, Pride in Place phases 1–2. Grain: authority. Window: Every round to date."},"priceTrend":{"description":"Direction of prices over twelve months: rising, stable or cooling. Source: UK House Price Index. Grain: authority. Window: Twelve months to the newest non-provisional month at the dataset build."},"priceChange12mPct":{"description":"Twelve-month house price change, percent. Source: UK House Price Index. Grain: authority. Window: Twelve months to the newest non-provisional month at the dataset build."},"crimeIndex":{"description":"Recorded crime per resident and worker against the national median district, 100 = typical, lower is safer. Absent where the police force publishes nothing. Source: Police.uk street-level crime; ONS population and workplace counts. Grain: place. Window: The latest twelve months published."},"privateRentedPct":{"description":"Share of households renting privately, percent. Source: Census 2021. Grain: place. Window: Census day, 2021."},"degreePct":{"description":"Share of residents aged 16+ with a degree-level qualification, percent. Source: Census 2021. Grain: place. Window: Census day, 2021."},"householdIncomeAfterHousing":{"description":"Modelled mean household income after housing costs, GBP a year. Source: ONS small area income estimates (MSOA). Grain: place. Window: The financial year named in householdIncomeYear."},"householdIncomeYear":{"description":"The financial year householdIncomeAfterHousing describes. Source: ONS small area income estimates. Grain: place. Window: As stated."},"gigabitBroadbandPct":{"description":"Share of premises able to order gigabit broadband, percent. Source: Ofcom Connected Nations. Grain: place. Window: The latest release."},"councilTaxBandABPct":{"description":"Share of dwellings in council tax bands A and B, percent. Source: Valuation Office Agency council tax stock. Grain: place. Window: The latest release."},"councilTaxBandD":{"description":"Band D council tax including precepts, GBP a year. Source: The authority's published charge. Grain: authority. Window: The latest financial year published."},"stateSchools":{"description":"State-funded schools in the place's districts. England only. Source: Ofsted. Grain: place. Window: The latest release."},"schoolsGoodOrBetterPct":{"description":"Share of graded schools judged Good or Outstanding, percent. A grade from before Ofsted's November 2025 framework. Source: Ofsted. Grain: place. Window: The latest legacy grade per school."},"schoolsGraded":{"description":"How many schools schoolsGoodOrBetterPct is of. Source: Ofsted. Grain: place. Window: As schoolsGoodOrBetterPct."},"listedBuildings":{"description":"Listed buildings in the place's districts. England only. Source: Historic England. Grain: place. Window: The list as at the dataset build."},"longTermVacantPct":{"description":"Homes empty more than six months, percent of stock. Source: MHCLG Live Table 615. Grain: authority. Window: The latest release."},"salesTurnoverPct":{"description":"Residential sales in the year as a share of dwelling stock, percent. Source: Land registrations over dwelling stock. Grain: authority. Window: The latest twelve months of registrations."},"priceChange5yPct":{"description":"Five-year house price change, percent. Source: UK House Price Index. Grain: authority. Window: Five years to the newest non-provisional month at the dataset build."},"priceChange10yPct":{"description":"Ten-year house price change, percent. Where negative, the ranking takes the annualised fall off grossYield before scoring it, because a yield in a falling market is partly the fall. Source: UK House Price Index. Grain: authority. Window: Ten years to the newest non-provisional month at the dataset build."},"priceFromPeakPct":{"description":"How far the latest twelve-month average price sits below the highest twelve-month average in the series, percent; 0 is at the peak. Source: UK House Price Index. Grain: authority. Window: The series from 1995 (2004 in Scotland) to the newest non-provisional month."},"pricePeakMonth":{"description":"The month the highest twelve-month window ended, YYYY-MM. Source: UK House Price Index. Grain: authority. Window: As priceFromPeakPct."},"dominantIndustry":{"description":"The SIC 2007 section holding at least three times its Great Britain share of the authority's employee jobs, and at least 5% of them. Absent where none does. Source: ONS Business Register and Employment Survey (BRES), via NOMIS. Grain: authority. Window: The latest BRES year."},"dominantIndustrySharePct":{"description":"dominantIndustry's share of the authority's employee jobs, percent. Source: ONS BRES. Grain: authority. Window: The latest BRES year."},"dominantIndustryGbSharePct":{"description":"The same section's share of employee jobs across Great Britain, percent. Source: ONS BRES. Grain: region. Window: The latest BRES year."},"dominantIndustryJobs":{"description":"Employee jobs in dominantIndustry across the authority. Source: ONS BRES. Grain: authority. Window: The latest BRES year."},"dominantIndustryJobsBase":{"description":"Employee jobs in dominantIndustry across the authority in 2015, the first year of the current BRES series. Source: ONS BRES. Grain: authority. Window: 2015."},"employeeJobsChangePct":{"description":"Change in all employee jobs across the authority over employeeJobsPeriod, percent. Source: ONS BRES. Grain: authority. Window: As employeeJobsPeriod."},"employeeJobsPeriod":{"description":"The BRES years employeeJobsChangePct spans, e.g. 2015-2024. Source: ONS BRES. Grain: authority. Window: As stated."},"epcBelowCPct":{"description":"Share of lodged energy performance certificates below band C across the place's postcode districts, pooled by certificate: an area proxy for the stock likely to need energy-efficiency work, not a survey of any home. Source: MHCLG Energy Performance of Buildings register (England and Wales); Scottish Government domestic EPC register (Scotland). Grain: place. Window: Every certificate lodged in the register's current release."},"epcCertificates":{"description":"How many certificates epcBelowCPct is of. Source: As epcBelowCPct. Grain: place. Window: As epcBelowCPct."},"epcPrivateRentedBelowCPct":{"description":"The same share for privately rented homes. Scotland only. Source: Scottish Government domestic EPC register. Grain: place. Window: As epcBelowCPct."},"forecast5yPct":{"description":"A named forecaster's five-year house price forecast for the region, percent. A forecast, not a measurement. Source: As named in forecastSource. Grain: region. Window: The forecaster's latest published edition."},"forecastSource":{"description":"Who made forecast5yPct, and for which region. Source: As stated. Grain: region. Window: As stated."}}},"summary":{"type":"array","items":{"type":"string"}},"postcodeDistricts":{"type":"array","items":{"type":"string"}},"attribution":{"type":"string"}}}},"asOf":{"type":"object"},"notes":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Not a postcode or district. Free."},"402":{"description":"Payment required. The PAYMENT-REQUIRED header carries the x402 v2 requirements (scheme exact, USDC on Base). Retry with a PAYMENT-SIGNATURE header."},"404":{"description":"Not in a ranked place. Free."},"429":{"description":"Rate limited."}}}},"/api/v1/search":{"get":{"operationId":"searchLocations","summary":"Up to 10 places matching a budget, yield, kind of home and location. $0.25 a call.","description":"Headline figures per place, with a detailUrl to the district call for the rest. A malformed query, or one nothing matches, is answered before payment, free.","x-payment":{"protocol":"x402","version":2,"scheme":"exact","price":"$0.25","asset":"USDC","network":"eip155:8453","payTo":"0x407DCFDd5B583c07cBAdd2Ba5cFE907ac7988f77"},"parameters":[{"name":"budget","in":"query","schema":{"type":"number"},"example":150000,"description":"Most the buyer will pay for one home, GBP."},{"name":"minYield","in":"query","schema":{"type":"number"},"example":6,"description":"Lowest gross yield, percent. Unmeasured yields never pass."},{"name":"propertyType","in":"query","schema":{"type":"string","enum":["flat","terraced","semi-detached","any"]},"description":"The kind of home the yield is measured on."},{"name":"near","in":"query","schema":{"type":"string"},"example":"M1","description":"A UK postcode, postcode district or 'latitude,longitude'."},{"name":"radiusKm","in":"query","schema":{"type":"number","default":40,"maximum":300}},{"name":"sort","in":"query","schema":{"type":"string","enum":["match","yield","growth","demand","price"]},"description":"match (Clarity's ranking against budget, the default when budget is given), yield (the default otherwise), growth, demand, price (cheapest first)."},{"name":"priority","in":"query","schema":{"type":"string","enum":["yield","balanced","growth"],"default":"balanced"},"description":"For sort=match."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":10}}],"responses":{"200":{"description":"matched (how many places pass the filters) and up to limit results."},"400":{"description":"A parameter is out of range. Free."},"402":{"description":"Payment required. The PAYMENT-REQUIRED header carries the x402 v2 requirements (scheme exact, USDC on Base). Retry with a PAYMENT-SIGNATURE header."},"429":{"description":"Rate limited."}}}},"/api/v1/deal":{"get":{"operationId":"checkDeal","summary":"Judge a buy-to-let at a price and postcode: purchase tax, lender cover, cashflow, yields, stress tests, objections and a verdict. $0.50 a call; LS6 free.","description":"Runs the purchase through the Clarity location report for the authority the postcode is in: the same deal model, purchase tax (SDLT in England, LTT in Wales, LBTT with the Additional Dwelling Supplement in Scotland), objections and verdict (CLEARS, MARGINAL or DOES NOT CLEAR) the PDF prints. A modelled purchase in an area, not a valuation of an address. A malformed query, an uncovered district or a district with no report is refused before payment, free.","x-payment":{"protocol":"x402","version":2,"scheme":"exact","price":"$0.50","asset":"USDC","network":"eip155:8453","payTo":"0x407DCFDd5B583c07cBAdd2Ba5cFE907ac7988f77"},"parameters":[{"name":"postcode","in":"query","schema":{"type":"string"},"example":"M14 5RX","description":"A UK postcode or postcode district. Give this or district."},{"name":"district","in":"query","schema":{"type":"string"},"description":"A postcode district, in place of postcode."},{"name":"price","in":"query","required":true,"schema":{"type":"number","minimum":10000,"maximum":20000000},"example":180000,"description":"Asking price, GBP."},{"name":"rent","in":"query","schema":{"type":"number","minimum":100,"maximum":50000},"description":"Expected rent, GBP a month. Default: the ONS median for the kind of home in the authority."},{"name":"propertyType","in":"query","schema":{"type":"string","enum":["flat","terraced","semi-detached","detached"]},"description":"Picks the rent and the comparables. Default: the report's entry-level stock."},{"name":"deposit","in":"query","schema":{"type":"number","minimum":5,"maximum":100,"default":25},"description":"Deposit, percent of price."},{"name":"cash","in":"query","schema":{"type":"number","minimum":0},"description":"Buyer's cash available, GBP. Given, the check tests whether it covers the cash needed; absent, that test is skipped."},{"name":"mortgage","in":"query","schema":{"type":"boolean","default":true},"description":"false models a cash purchase."},{"name":"otherPropertyOwned","in":"query","schema":{"type":"boolean","default":true},"description":"true applies the additional-dwelling purchase tax rates."},{"name":"ukResident","in":"query","schema":{"type":"boolean","default":true},"description":"false adds England's 2% non-resident surcharge."}],"responses":{"200":{"description":"One assessment per report covering the district (verdict, objections, wrongIf, inputs, deal, pricePosition, checks), plus asOf.mortgageRate and notes."},"400":{"description":"A parameter is missing or out of range. Free."},"402":{"description":"Payment required. The PAYMENT-REQUIRED header carries the x402 v2 requirements (scheme exact, USDC on Base). Retry with a PAYMENT-SIGNATURE header."},"404":{"description":"Not in a ranked place, or no report covers it yet. Free."},"429":{"description":"Rate limited."},"503":{"description":"The report could not be read. Not charged."}}}}}}