# ProofPrice: full reference for AI agents

> Real prices actually paid, not asking prices. Ask "what did people actually pay for X, here, recently?" and get a range (median, 10th–90th percentile) with sample size, period, confidence, source and licence. Built from official open data. Aggregates only. Free, no API key.

This file is generated from the live service, so it always matches what is deployed.
Short version: https://proofprice.com/llms.txt · OpenAPI 3.1: https://proofprice.com/openapi.json · Setup for AI clients: https://proofprice.com/connect · Method: https://proofprice.com/method
Privacy notice: https://proofprice.com/privacy · Terms of use: https://proofprice.com/terms
Contact: hello@proofprice.com

## How to connect
- MCP server (Streamable HTTP, no key, no sign-in): https://proofprice.com/api/mcp
- REST (GET, JSON, CORS open): https://proofprice.com/api/v1/<category>
- Add-to-client instructions for Claude, ChatGPT, Cursor, VS Code, Windsurf, Claude Code and agent frameworks: https://proofprice.com/connect

## Tools (MCP) and endpoints (REST)

### pricepaid_car_prices  —  Car-related prices actually paid
REST: GET https://proofprice.com/api/v1/cars
Countries: SG
Description: Use this when a user asks what people actually paid for the right to own or buy a car (for example Singapore's Certificate of Entitlement, COE) in Singapore car ownership rights (COE) (country SG). Returns the median winning price, a typical range (10th–90th percentile), the number of bidding rounds or sales, the period covered, a confidence label, and the official source and licence. Do not use for asking prices, dealer listings, or other countries.
Parameters (the same names work as MCP tool arguments and REST query parameters):
  - country (one of, required)
    SG = Singapore COE (Certificate of Entitlement) bidding results
    Allowed values: SG
  - product (one of, optional)
    Which price. 'coe' = Singapore Certificate of Entitlement bidding results. Default 'coe'. SG: 'coe'.
    Allowed values: coe
  - months (integer, optional, min 1, max 60)
    How many recent months to include. Default 12.
  - vehicle_class (one of, optional)
    SG only: COE category. A = cars up to 1600cc (default), B = cars above 1600cc, C = goods vehicles/buses, D = motorcycles, E = open.
    Allowed values: A, B, C, D, E
Example requests:
  - REST: GET https://proofprice.com/api/v1/cars?country=SG&product=coe&vehicle_class=A
    MCP: call pricepaid_car_prices with {"country":"SG","product":"coe","vehicle_class":"A"}   (source: sg-coe)
  - REST: GET https://proofprice.com/api/v1/cars?country=SG&product=coe&vehicle_class=D&months=24
    MCP: call pricepaid_car_prices with {"country":"SG","product":"coe","vehicle_class":"D","months":24}   (source: sg-coe)

### pricepaid_fuel_prices_now  —  Live fuel prices at the pump
REST: GET https://proofprice.com/api/v1/fuel
Countries: ES, FR, IT
Description: Use this when a user asks the current price of petrol, diesel, E10, E85, LPG or CNG near a place in Spain, France or Italy, or where fuel is cheapest there. Returns the median and typical range of pump prices across stations in the area, the three cheapest stations, and the official source and licence. How fresh: Spain: several times a day; France: about every 10 minutes; Italy: daily (prices at 08:00 of the extraction day). Do not use for other countries or for historical prices.
Parameters (the same names work as MCP tool arguments and REST query parameters):
  - country (one of, required)
    ES = Spain; FR = France; IT = Italy
    Allowed values: ES, FR, IT
  - fuel (one of, required)
    petrol95 = unleaded 95; methane = CNG (priced per kg). Italy: diesel, petrol95, lpg, methane only.
    Allowed values: diesel, petrol95, petrol98, e10, e85, lpg, methane
  - postcode (string, optional)
    Postcode of the place. ES: 5-digit postcode, e.g. '28001'. FR: 5-digit postcode, e.g. '75015'.
  - area (string, optional)
    Wider area when no postcode. ES: province code ('28' = Madrid). FR: department ('69', '2A'). IT: province ('MI', 'RM').
  - town (string, optional)
    Town name. ES: town name, e.g. 'Valencia'. IT: comune name, e.g. 'Bologna'.
  - service (one of, optional)
    Self-service or attended service, where a country prices them differently. IT: self-service (default) or attended service, which costs more.
    Allowed values: self, served
Example requests:
  - REST: GET https://proofprice.com/api/v1/fuel?country=ES&area=42&fuel=diesel
    MCP: call pricepaid_fuel_prices_now with {"country":"ES","area":"42","fuel":"diesel"}   (source: es-fuel)
  - REST: GET https://proofprice.com/api/v1/fuel?country=ES&postcode=28001&fuel=petrol95
    MCP: call pricepaid_fuel_prices_now with {"country":"ES","postcode":"28001","fuel":"petrol95"}   (source: es-fuel)
  - REST: GET https://proofprice.com/api/v1/fuel?country=FR&postcode=75015&fuel=diesel
    MCP: call pricepaid_fuel_prices_now with {"country":"FR","postcode":"75015","fuel":"diesel"}   (source: fr-fuel)
  - REST: GET https://proofprice.com/api/v1/fuel?country=IT&area=MI&fuel=diesel
    MCP: call pricepaid_fuel_prices_now with {"country":"IT","area":"MI","fuel":"diesel"}   (source: it-fuel)
History: pricepaid_fuel_price_history / GET https://proofprice.com/api/v1/fuel/history takes the same parameters plus days (integer, 2–366, default 30).
  Use this when a user asks how pump prices have changed over recent days or weeks in a place, or whether fuel is getting cheaper. Returns the daily median and typical range of pump prices in the area, with the change over the period, from our daily snapshots of official data. Do not use for today's cheapest stations (use pricepaid_fuel_prices_now).
  The MCP history tool is offered once the price library holds 7 days; the REST endpoint always answers (it says when history is still building).

### pricepaid_home_sales  —  Home sale prices actually paid
REST: GET https://proofprice.com/api/v1/home-sales
Countries: FR, GB, IE, SG
Description: Use this when a user asks what homes actually sold for in a town or area, what a fair price for a home is, or how much property costs there, in France (country FR), England & Wales (country GB), Ireland (country IE) or Singapore public housing (country SG). Returns the median sale price, a typical range (10th–90th percentile), the number of sales, the period covered, a confidence label, and the official source and licence, from government sale records. Do not use for rents, asking prices, commercial property, or other countries.
Parameters (the same names work as MCP tool arguments and REST query parameters):
  - country (one of, required)
    FR = France (DVF); GB = England & Wales (HM Land Registry); IE = Ireland (Property Price Register); SG = Singapore HDB resale flats
    Allowed values: FR, GB, IE, SG
  - town (string, optional)
    Town or city. FR: town, e.g. 'Bordeaux', or use postcode. GB: required, e.g. 'Bristol'. IE: a county ('Cork') or Dublin postal district ('Dublin 6'). Omit for all of Ireland. SG: required, e.g. 'Tampines'.
  - postcode (string, optional)
    Postcode, for a precise area. FR: 5-digit postcode, e.g. '69003'; use instead of town for a precise area.
  - property_type (one of, optional)
    Kind of home. Default 'any'. FR: house or apartment. GB: detached, semi-detached, terraced or flat-maisonette. IE: any, new or second-hand (new homes are usually recorded without VAT).
    Allowed values: house, apartment, detached, semi-detached, terraced, flat-maisonette, new, second-hand, any
  - months (integer, optional, min 1, max 36)
    How many recent months to include. Default 12. IE: rounded to the nearest of 3, 6, 12, 24 or 36.
  - postcode_district (string, optional)
    GB only: postcode district such as 'BS8' to narrow the area.
  - county (string, optional)
    IE only: same as town; a county such as 'Dublin' or 'Cork'.
  - flat_type (one of, optional)
    SG only: HDB flat type.
    Allowed values: 1 ROOM, 2 ROOM, 3 ROOM, 4 ROOM, 5 ROOM, EXECUTIVE, MULTI-GENERATION
Example requests:
  - REST: GET https://proofprice.com/api/v1/home-sales?country=FR&postcode=69003&property_type=apartment
    MCP: call pricepaid_home_sales with {"country":"FR","postcode":"69003","property_type":"apartment"}   (source: fr-dvf)
  - REST: GET https://proofprice.com/api/v1/home-sales?country=GB&town=Bristol&property_type=terraced
    MCP: call pricepaid_home_sales with {"country":"GB","town":"Bristol","property_type":"terraced"}   (source: gb-hmlr-ppd)
  - REST: GET https://proofprice.com/api/v1/home-sales?country=IE&town=Dublin&property_type=second-hand
    MCP: call pricepaid_home_sales with {"country":"IE","town":"Dublin","property_type":"second-hand"}   (source: ie-ppr)
  - REST: GET https://proofprice.com/api/v1/home-sales?country=IE&town=Dublin+6&months=24
    MCP: call pricepaid_home_sales with {"country":"IE","town":"Dublin 6","months":24}   (source: ie-ppr)
  - REST: GET https://proofprice.com/api/v1/home-sales?country=SG&town=Tampines
    MCP: call pricepaid_home_sales with {"country":"SG","town":"Tampines"}   (source: sg-hdb-resale)
  - REST: GET https://proofprice.com/api/v1/home-sales?country=SG&town=Tampines&flat_type=4+ROOM
    MCP: call pricepaid_home_sales with {"country":"SG","town":"Tampines","flat_type":"4 ROOM"}   (source: sg-hdb-resale)

### pricepaid_coverage  —  What price data is covered
REST: GET https://proofprice.com/api/v1/coverage
Description: Which countries, categories and official sources the price-paid tools cover, with each source's licence and update frequency. Takes no parameters. Call it first when unsure whether a place is covered.

## Answer format (every endpoint and tool)
JSON with: query, status ("ok" or not), price {currency, unit, median, typical_low, typical_high, min, max}, sample_size, period {from, to}, confidence (low / medium / high), price_type ("transaction" or "posted_pump_price"), as_of, source {id, name, publisher, licence, licence_url, attribution, url}, method, method_url, summary (one plain sentence), notice, and an optional extra object.
typical_low and typical_high are the 10th and 90th percentiles.

Confidence: high = 50+ records, medium = 15–49, low = 5–14. Below 5 records no figure is returned.
Errors: HTTP 400 with {error, detail} for a missing or invalid parameter or an uncovered country; 502 when the official source cannot be reached. MCP tools return isError with a plain message.

## Rules for citing
- Cite the source and attribution line returned with each answer.
- Home figures are prices paid (transactions). Fuel figures are posted pump prices, not receipts.
- Never treat a range as an asking price. Figures from fewer than 5 records are not returned.
- This is information, not a valuation, offer or advice.

## Method
- Every answer is a range: the median and the 10th–90th percentile of recorded prices, with sample size, period and confidence.
- Aggregates only: no individual addresses or personal data are returned for home sales.
- Price library: once a day ProofPrice snapshots each live source that supports history and keeps, per area and item, the median, 10th–90th percentile and count. Days with fewer than 5 records are not shown.
- Asking prices are never presented as paid prices. Fuel figures are labelled as posted pump prices.
- France (DVF): only plain sales of exactly one house or apartment are counted; sales that bundle several homes or commercial premises are left out. DVF arrives with a delay of several months, so the period shown is the latest available.
- England & Wales: standard-price sales (category A) only; repossessions and transfers to companies are excluded.
- Ireland (Property Price Register): the register is collected once a day into our price library; answers are rolling 3 to 36 month windows by county or Dublin postal district, full-market-price sales only. New homes are usually recorded without VAT.
- Italy: prices in force at 08:00 on the extraction day, self-service unless asked otherwise; prices not updated in 30 days are left out.
- Singapore COE: median of the winning premium across bidding rounds from the Land Transport Authority's official results.
- Full method page: https://proofprice.com/method

## Sources, licences and attribution
### Precios de carburantes en las estaciones de servicio terrestres (es-fuel)
- Country: ES · Category: fuel (pump prices) · Status: live
- Publisher: Ministerio para la Transición Ecológica y el Reto Demográfico (Geoportal de hidrocarburos), via datos.gob.es
- What is recorded: Current pump price at each public filling station in Spain, by fuel type.
- Price type: posted_pump_price · Freshness: Several times a day
- Licence: Spanish public-sector information reuse terms (Ley 37/2007, RD 1495/2011): reuse allowed with the source and update date cited. Exact licence text to be confirmed. (https://datos.gob.es/en/catalogo/e05068001-precio-de-carburantes-en-las-gasolineras-espanolas)
- Attribution to show: Source: Ministerio para la Transición Ecológica y el Reto Demográfico – precios de carburantes (datos.gob.es).
- Homepage: https://geoportalgasolineras.es/
- Limits: Posted pump prices, not individual receipts. Restricted-sale stations are excluded.

### Demandes de valeurs foncières (DVF), geo-dvf per-commune files (fr-dvf)
- Country: FR · Category: home sales · Status: live
- Publisher: Direction générale des Finances publiques (DGFiP), files prepared by Etalab
- What is recorded: Property sales recorded by French land registries: date, nature, price, type of property, built surface.
- Price type: transaction · Freshness: Twice a year, with a delay of several months
- Licence: Licence Ouverte / Etalab 2.0, plus the DVF reuse conditions (no re-identification of people; raw data not to be indexed by search engines) (https://www.data.gouv.fr/fr/datasets/demandes-de-valeurs-foncieres/)
- Attribution to show: Source: DGFiP, Demandes de valeurs foncières (DVF), via geo-dvf (Etalab), Licence Ouverte 2.0.
- Homepage: https://www.data.gouv.fr/fr/datasets/demandes-de-valeurs-foncieres-geolocalisees/
- Limits: We return aggregates only (median, range, count), never addresses or parcels. Alsace-Moselle and Mayotte are not covered by DVF.

### Prix des carburants en France – flux instantané v2 (fr-fuel)
- Country: FR · Category: fuel (pump prices) · Status: live
- Publisher: Ministère de l'Économie via data.economie.gouv.fr
- What is recorded: Current pump price per litre at each filling station, by fuel type, with last-update time.
- Price type: posted_pump_price · Freshness: About every 10 minutes
- Licence: Licence Ouverte / Etalab 2.0 (https://www.etalab.gouv.fr/licence-ouverte-open-licence/)
- Attribution to show: Source: Ministère de l'Économie – prix des carburants (Licence Ouverte / Etalab 2.0).
- Homepage: https://data.economie.gouv.fr/explore/dataset/prix-des-carburants-en-france-flux-instantane-v2/
- Limits: Pump prices are what every customer pays at that station at that moment; they are posted prices, not individual receipts.

### Price Paid Data (gb-hmlr-ppd)
- Country: GB (England & Wales) · Category: home sales · Status: live
- Publisher: HM Land Registry
- What is recorded: Residential property sales: price paid, completion date, property type, address.
- Price type: transaction · Freshness: Monthly
- Licence: Open Government Licence v3.0 (https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/)
- Attribution to show: Contains HM Land Registry data © Crown copyright and database right. This data is licensed under the Open Government Licence v3.0.
- Homepage: https://www.gov.uk/government/statistical-data-sets/price-paid-data-downloads
- Limits: We return aggregates only (median, range, count), never individual addresses. Standard-price sales only (category A).

### Residential Property Price Register (ie-ppr)
- Country: IE (Ireland) · Category: home sales · Status: live
- Publisher: Property Services Regulatory Authority (PSRA), Ireland
- What is recorded: Residential property sales declared to Revenue for stamp duty: price paid, sale date, county, new or second-hand.
- Price type: transaction · Freshness: Updated about monthly; sales appear a few weeks after they happen
- Licence: Creative Commons Attribution 4.0 (PSRA open data; wording to be confirmed with the publisher) (https://creativecommons.org/licenses/by/4.0/)
- Attribution to show: Source: Property Services Regulatory Authority (PSRA), Residential Property Price Register. Licensed under CC BY 4.0.
- Homepage: https://www.propertypriceregister.ie/
- Limits: Aggregates only, by county or Dublin postal district and rolling window; never individual addresses. Excludes sales flagged 'not full market price' and records above EUR 10 million (bulk sales). New homes are usually recorded without VAT.

### Carburanti – Prezzi praticati e anagrafica degli impianti (it-fuel)
- Country: IT · Category: fuel (pump prices) · Status: live
- Publisher: Ministero delle Imprese e del Made in Italy (MIMIT), Osservaprezzi carburanti
- What is recorded: Pump prices in force at 08:00 each day at every station in Italy, by fuel and service type (self or attended).
- Price type: posted_pump_price · Freshness: Daily (prices at 08:00 of the extraction day)
- Licence: Italian Open Data Licence v2.0 (IODL 2.0) (https://www.dati.gov.it/content/italian-open-data-license-v20)
- Attribution to show: Fonte: Ministero delle Imprese e del Made in Italy – Osservaprezzi carburanti (IODL 2.0).
- Homepage: https://www.mimit.gov.it/it/open-data/elenco-dataset/carburanti-prezzi-praticati-e-anagrafica-degli-impianti
- Limits: Posted pump prices, not individual receipts. Prices not updated in 30 days are left out.

### COE bidding results and prices (sg-coe)
- Country: SG · Category: cars (Certificate of Entitlement) · Status: live
- Publisher: Land Transport Authority via data.gov.sg
- What is recorded: Result of each COE bidding exercise by vehicle category: quota, successful bids, bids received and the premium (the price every successful bidder paid).
- Price type: transaction · Freshness: Two bidding rounds a month; updated after each round
- Licence: Singapore Open Data Licence v1.0 (https://data.gov.sg/open-data-licence)
- Attribution to show: Contains information from COE Bidding Results and Prices accessed from data.gov.sg, made available under the terms of the Singapore Open Data Licence version 1.0.
- Homepage: https://data.gov.sg/datasets/d_69b3380ad7e51aff3a7dcc84eba52b8a/view
- Limits: The COE is the legal right to own a car in Singapore for 10 years, not the car itself. One premium per bidding round and category; all successful bidders pay the same premium.

### Resale flat prices (from Jan 2017) (sg-hdb-resale)
- Country: SG · Category: home sales (public housing resale) · Status: live
- Publisher: Housing & Development Board via data.gov.sg
- What is recorded: HDB resale transactions: month, town, flat type, floor area, lease, resale price.
- Price type: transaction · Freshness: Daily updates of registered resales
- Licence: Singapore Open Data Licence v1.0 (https://data.gov.sg/open-data-licence)
- Attribution to show: Contains information from Resale flat prices accessed from data.gov.sg, made available under the terms of the Singapore Open Data Licence version 1.0.
- Homepage: https://data.gov.sg/datasets/d_8b84c4ee58e3cfc0ece0d773c8ca6abc/view
- Limits: Public housing (HDB) only; private condominium sales are a separate source (not yet included).

## Coming next
- Verified used-phone receipts
- More countries: Taiwan, South Korea, Japan, NSW (Australia)
- Daily price history (fuel) from the ProofPrice price library

## Contact
- hello@proofprice.com