Taxon Partner API

1.Overview

One request per address, one data bundle for the valuation case: the basic package (comparables, neighbourhood statistics, amenities, parcel and price map) and, as a separate option, an indicative valuation (AVM). For reseller partners who show the data in their own software.

2.Authentication

Every request carries the header X-Api-Key. The key is long-lived, bound to your partner account and stored by Taxon as a hash only. You see it exactly once, in the partner dashboard (see "Managing your keys" below).

• Secrecy. The key stays in your backend. Never in a browser, a mobile app or a public repository. Call the API server to server.
• Rotation. You rotate a live key yourself in the partner dashboard (see "Managing your keys" below): the new key is shown once, the old one keeps working for 7 days with the notice key_rotation_pending, then answers 403 key_revoked.
• IP allowlist. Optionally the key can be restricted to the IP addresses of your servers (403 ip_not_allowed from any other address).
• Leak or suspected abuse: rotate or revoke the key yourself at once in the dashboard and report it within 48 hours; Taxon then revokes the old key immediately when needed.

Managing your keys 2.3.0

Since 08-09-2026 you manage your keys yourself in the partner dashboard on taxon.be (taxon.be/api_partner, section "Management"). Every action there is logged (who, when, from which IP address) and reported to Taxon; a key value never appears in a log or an e-mail.

Error codes of the dashboard actions (shown as text in the dashboard, never on /address or /usage): key_already_revealed, reveal_expired, not_revealable, key_limit_reached, live_key_not_allowed, not_self_revocable.

3.Headers

Every response (errors included) contains the header X-Request-ID and the field request_id. Quote it in every support question.

4.GET /address

Delivers the requested sections for one address in Flanders, Wallonia or Brussels. Processing: validation, cap check, geocoding, dedup check, sections fetched in parallel, billing, response. Typical response time 1 to 8 seconds (AVM and parcel are the slowest; several parcels 3 to 12 seconds); set your client timeout to at least 60 seconds.

Query parameters

Example request

GET /api/v1/partner/address?address=Doorniksestraat%2040%2C%208500%20Kortrijk&sections=basic,avm&type=apartment&living_area_m2=95 HTTP/1.1
Host: taxonapi.be
X-Api-Key: tx_live_<32 hex>
X-User-Ref: office-kortrijk-03
X-Case-Ref: DOS-2026-0452
Idempotency-Key: 2c6a8b1e-3f4d-4a5b-9c7e-1d2f3a4b5c6d
Accept-Language: en

Example response (200)

Live response of 08-09-2026 (live key, user office-kortrijk-03, request cf514c7de2714c11806e2ebf053d0247), shortened to one comparable per block and three amenities; the price_map block (part of the basic package) is omitted here, see section 5. With a live key environment is live, charged is true and free_reason is null; the amounts in billing.price are those of the agreement of the client used for the capture, yours follow your own agreement. With a test key environment is test, charged is false, free_reason is test and every amount is 0.00.

{
  "request_id": "cf514c7de2714c11806e2ebf053d0247",
  "environment": "live",
  "address": {
    "input": "Doorniksestraat 40, 8500 Kortrijk",
    "normalized": "Doorniksestraat 40, 8500 Kortrijk",
    "box": null,
    "postal_code": "8500",
    "municipality": "Kortrijk",
    "lat": 50.82541,
    "lon": 3.267149,
    "region": "VL",
    "nis_code": "34022",
    "geocoder": "geo.api.vlaanderen.be",
    "geocode_score": 0.95,
    "precision": "house_number"
  },
  "sections_delivered": ["basic", "parcel", "avm", "price_map"],
  "basic": {
    "comparables": [
      {
        "type": "apartment",
        "type_label": "apartment",
        "transaction": "sale",
        "transaction_label": "for sale",
        "address_mode": "house_number",
        "radius_m": 1000,
        "count": 25,
        "excluded_subject_property": 0,
        "max_age_months": 24,
        "items": [
          {
            "ref": "r_1a30b3b90e",
            "address": "Schouwburgplein 10, 8500 Kortrijk",
            "distance_m": 157,
            "type": "apartment",
            "transaction": "sale",
            "price": 250000,
            "price_kind": "asking_price",
            "price_kind_label": "asking price",
            "price_per_m2": 2427,
            "living_area_m2": 103,
            "plot_area_m2": null,
            "bedrooms": 2,
            "epc_label": "B",
            "epc_kwh_m2": 108.0,
            "epc_source": "as advertised",
            "year_built": 1980,
            "condition": "good condition",
            "building_type": "terraced",
            "new_build": false,
            "published": "2026-07-16",
            "days_online": 12,
            "last_seen": "2026-07-28",
            "status": "offline",
            "status_label": "offline",
            "source": "listing",
            "source_label": "listing",
            "features": {
              "garage": true,
              "parking_spaces": 1,
              "terrace": true,
              "terrace_m2": null,
              "garden": null,
              "garden_m2": null,
              "cellar": true,
              "attic": null,
              "floor": 2,
              "floors_count": 5,
              "elevator": false,
              "kitchen": "semi_equipped",
              "bathrooms": 1,
              "shower_rooms": null,
              "toilets": 1,
              "heating": "gas",
              "solar_panels": false,
              "double_glazing": true,
              "orientation_garden": null,
              "renovation_year": null,
              "inspections": {"electrical_compliant": null, "asbestos_certificate": null, "oil_tank": null},
              "flood_zone": "none"
            },
            "summary": "Apartment on the 2nd floor of 103 m² with garage, terrace and cellar, 2 bedrooms, EPC B, built in 1980.",
            "thumbnail": {"url": "https://taxonapi.be/api/v1/marketexplorer/foto/<token>?w=160", "valid_until": "2026-09-08T09:39:16Z"},
            "photo_count": 12,
            "history": [
              {"date": "2026-04-29", "price": 250000, "event": "published", "label": "published"},
              {"date": "2026-07-28", "price": null, "event": "offline", "label": "offline"}
            ],
            "photos": [
              {"url": "https://taxonapi.be/api/v1/marketexplorer/foto/<token>?w=640", "download_token": "b71c6e8f1c51a562f33d", "valid_until": "2026-09-08T09:39:16Z"},
              {"url": "https://taxonapi.be/api/v1/marketexplorer/foto/<token>?w=640", "download_token": "4bdfcfbd9ea0c282e886", "valid_until": "2026-09-08T09:39:16Z"}
            ]
          }
        ]
      },
      {
        "type": "apartment",
        "type_label": "apartment",
        "transaction": "rent",
        "transaction_label": "for rent",
        "address_mode": "house_number",
        "radius_m": 1000,
        "count": 25,
        "excluded_subject_property": 0,
        "max_age_months": 24,
        "items": ["…"]
      }
    ],
    "neighbourhood": {
      "sector": {"code": "34022A00-", "name": "KORTRIJK-CENTRUM", "level": "sector", "municipality": "Kortrijk"},
      "building_stock": {
        "level": "sector",
        "reference_date": "2026-01-01",
        "total": 2882,
        "distribution": [
          {"category": "residential", "label": "Residential", "count": 1908, "pct": 66.2},
          {"category": "commerce_services", "label": "Commerce & services", "count": 383, "pct": 13.3},
          {"category": "industry", "label": "Industry", "count": 7, "pct": 0.2},
          {"category": "agriculture", "label": "Agriculture", "count": 0, "pct": 0.0},
          {"category": "other", "label": "Other", "count": 584, "pct": 20.3}
        ],
        "source": "FPS Finance - open patrimonial data"
      },
      "price_level": {
        "type": "apartment",
        "radius_m": 2000,
        "sale_per_m2": {"n": 430, "p25": 2260.25, "median": 2856.5, "p75": 3747.0},
        "rent_per_m2_year": {"n": 346, "p25": 89.12, "median": 105.85, "p75": 126.7},
        "gross_yield_pct": 3.71,
        "gross_yield_p25_p75": [3.12, 4.44],
        "price_kind": "asking_price"
      },
      "epc_prices": {
        "type": "apartment",
        "radius_m": 5000,
        "labels": {
          "B": {"median_per_m2": 2578.1, "count": 132},
          "C": {"median_per_m2": 2441.6, "count": 56},
          "A": {"median_per_m2": 3849.2, "count": 83},
          "D": {"median_per_m2": 2208.5, "count": 16},
          "F": {"median_per_m2": 1645.3, "count": 10},
          "A+": {"median_per_m2": 5432.6, "count": 6},
          "E": {"median_per_m2": 2521.7, "count": 4}
        },
        "price_kind": "asking_price"
      },
      "safety": {
        "level": "municipality",
        "municipality": "Kortrijk",
        "year": 2025,
        "burglaries_per_1000": 2.7,
        "crimes_per_1000": 89.0,
        "region_burglaries_per_1000": 2.1,
        "region_crimes_per_1000": 63.3,
        "years": [
          {"year": 2025, "burglaries_per_1000": 2.7, "crimes_per_1000": 89.0},
          {"year": 2024, "burglaries_per_1000": 3.2, "crimes_per_1000": 100.1},
          {"year": 2023, "burglaries_per_1000": 3.3, "crimes_per_1000": 101.9}
        ],
        "source": "Federal Police - Police Crime Statistics (PCS)"
      }
    },
    "amenities": {
      "score": 9.3,
      "scale": "0-10",
      "radius_m": 1000,
      "sub_scores": {
        "public_transport": {"score": 9.2, "label": "Public transport", "count": 17},
        "healthcare": {"score": 9.2, "label": "Healthcare", "count": 7},
        "shops": {"score": 9.8, "label": "Shops and catering", "count": 87},
        "sport_culture": {"score": 9.3, "label": "Sport and culture", "count": 12},
        "education": {"score": 8.9, "label": "Education", "count": 9}
      },
      "poi_count": 158,
      "top_10": [
        {"name": "Muskat Pureebar", "type": "shops", "type_label": "Shops and catering", "distance_m": 52},
        {"name": "KBC", "type": "shops", "type_label": "Shops and catering", "distance_m": 66},
        {"name": "Vork", "type": "shops", "type_label": "Shops and catering", "distance_m": 79}
      ],
      "attribution": "© OpenStreetMap contributors (ODbL)"
    }
  },
  "parcel": {
    "capakey": "34022G0494/00E000",
    "region": "VL",
    "area_m2": 259.14,
    "cadastral_area_m2": 259.14,
    "width_m": 4.79,
    "depth_m": 53.61,
    "frontage_m": 7.31,
    "built_area_m2": 164.1,
    "buildings_count": 2,
    "garden_orientation": "SW",
    "garden_orientation_deg": 247,
    "zoning": {"category": "residential", "label": "woongebieden", "plan": "gewestplan"},
    "preemption_right": {"status": "none", "source": "RVV thematic layer, right of pre-emption (Flanders)"},
    "source": "CadGIS (FPS Finance) / GRB Gbg - building at ground level (Digitaal Vlaanderen)",
    "main_parcel": "34022G0494/00E000",
    "parcels": [
      {
        "capakey": "34022G0494/00E000",
        "area_m2": 259.14,
        "cadastral_area_m2": 259.14,
        "width_m": 4.79,
        "depth_m": 53.61,
        "built_area_m2": 164.1,
        "buildings_count": 2,
        "zoning": {"category": "residential", "label": "woongebieden", "plan": "gewestplan"},
        "preemption_right": {"status": "none", "source": "RVV thematic layer, right of pre-emption (Flanders)"},
        "source": "CadGIS (FPS Finance) / GRB Gbg - building at ground level (Digitaal Vlaanderen)",
        "is_main": true,
        "distance_to_address_m": 0
      }
    ],
    "parcels_count": 1,
    "total_area_m2": 259.14,
    "cadastral_total_area_m2": 259.14,
    "zoning_combined": {"category": "residential", "label": "woongebieden", "plan": "gewestplan"},
    "preemption_right_combined": {"status": "none", "parcels": []},
    "parcels_not_found": [],
    "plot_area_source": "cadastre_main_parcel",
    "parcel_candidates": [
      {"capakey": "34022G0495/00C000", "area_m2": 370.75, "direction": "S", "built": true, "distance_m": 7},
      {"capakey": "34022G0493/00L000", "area_m2": 1224.37, "direction": "W", "built": true, "distance_m": 12},
      {"capakey": "34022G0490/00C000", "area_m2": 249.56, "direction": "W", "built": true, "distance_m": 32}
    ],
    "parcel_candidates_source": "CadGIS (FPS Finance), adjacent within 0.5 m; built-up via the regional buildings layer",
    "parcel_candidates_remark": null
  },
  "avm": {
    "value": 243995,
    "range": [190804, 312014],
    "range_90": [162820, 365641],
    "rental_value": 885,
    "rental_value_range": [859, 954],
    "confidence": {"score": 72.7, "label": "low", "fsd_pct": 24.59},
    "comparables_count": 19,
    "comparables_count_500m": 19,
    "comparables_count_1km": 19,
    "inputs_used": {
      "type": "apartment",
      "living_area_m2": 95.0,
      "year_built": null,
      "epc_label": null,
      "condition": null,
      "bedrooms": null,
      "plot_area_m2": null,
      "plot_area_source": null
    },
    "price_basis": "asking_price_model",
    "model": "taxon-avm v3.1"
  },
  "billing": {
    "user_ref": "office-kortrijk-03",
    "case_ref": "DOS-2026-0452",
    "charged": true,
    "pilot": false,
    "free_reason": null,
    "price": {"package": 3.0, "avm": 2.0, "total": 5.0, "currency": "EUR", "excl_vat": true},
    "dedup_of": null,
    "dedup_valid_until": "2026-10-08T10:39:24+02:00",
    "month": "2026-09",
    "month_to_date": {"cases": 3, "amount": 10.0},
    "pilot_status": null,
    "today": {"client_today": 13, "user_today": 1}
  },
  "notices": [],
  "upstream_errors": {},
  "attribution": "References: Taxon (taxon.be)",
  "disclaimer": "Asking prices from listings, not notarial sale prices. Data for internal use per case only; building a derived database is prohibited. The valuer decides, the AVM is a support tool.",
  "generated_at": "2026-09-08T10:39:24+02:00"
}

5.Sections

Basic package and AVM option (2.4.0). The sections basic, parcel and price_map form one basic package per case: sections=basic delivers the three together at one price (billing.price.package). The AVM is a separate option (sections=basic,avm, billing.price.avm). sections_delivered keeps listing the real sections.

Source of the parcel data (2.4.2). The parcel section reads the current cadastral parcel plan of the FPS Finance (CadGIS PlanParcellaire, running fiscal situation, today 01-01-2027). The yearly INSPIRE snapshot (01-01-2026) is only the fallback on an outage or an empty answer. The field fiscal_situation (on parcel, on every parcels[] item and on every parcel_candidates[] item) gives the ISO date of the fiscal situation the parcel comes from; source names the layer. The date is the fiscal situation since which the current version of this parcel applies: a parcel that has not changed for years keeps an older date (for example 2019-01-01), while the plan it is read from is always the running fiscal situation. An older date therefore does not mean outdated data; only 2026-01-01 combined with an INSPIRE source marks the yearly snapshot fallback. A parcel that was split or merged after the last snapshot (for example 45043C0460/00R000 in Kluisbergen: one parcel of 921 m² in the snapshot, 460R 392 m² + 460X 529 m² in the current plan) is therefore delivered in its current form.

Several parcels per property: first candidates, then capakeys

A terraced house with a separate garage or garden parcel, a farm with meadows, a villa on two cadastral parcels: the point parcel at the address is then only part of the property. The API solves this in two steps.

• Step 1: request without capakeys. The parcel section contains the point parcel (main_parcel, parcels[] with 1 item) and parcel_candidates[]: the adjacent parcels (at most 12), each with capakey, cadastral area_m2, direction relative to the main parcel (always N, E, S or W, language-independent), built (regional buildings layer; null when that layer was not available) and distance_m between the centroids. Cadastral basics only, no owner data. Show that list to the user (for example "33011I0172/00G000, 40 m², south, built" = the garage) and let them tick what belongs to the property.
• Step 2: request again with capakeys (the main parcel plus the ticked parcels, comma-separated, at most 10). The section then delivers parcels[] (per parcel capakey, area from geometry and cadastre, width/depth, built area, number of buildings, zoning, pre-emption right, distance_to_address_m, is_main) and the totals total_area_m2, cadastral_total_area_m2, zoning_combined (one object when all parcels are equal, otherwise a list with parcels[] per zoning), preemption_right_combined (yes as soon as one parcel falls in a perimeter, with the capakeys concerned), main_parcel (the parcel on which the address falls, otherwise the first one, with notice main_parcel_not_in_capakeys) and parcels_not_found[]. The section-level fields stay those of the main parcel. The AVM (type house) uses total_area_m2; avm.inputs_used.plot_area_source says cadastre_main_parcel, cadastre_<n>_parcels (n = number of delivered parcels, 2 to 10) or partner; the section field parcel.plot_area_source only carries the two cadastre values. For an apartment no plot area goes to the model (not even with capakeys).
• Dedup. Same user, same address: the basic package delivered in step 1 is not charged again (notice dedup with section: basic; billing.free_reason is dedup only when nothing new is delivered, otherwise null (charged), test or pilot), even though the parcel section is rebuilt with the new parcels. When you add the AVM option in step 2, you only pay that option. The same capakeys again within 30 days = answer from the ledger (from_cache: true). The same Idempotency-Key with other capakeys = 409 idempotency_conflict. parcel_candidates, parcel_candidates_source and parcel_candidates_remark are always present and null when capakeys was given. A cold parcel analysis can take up to 21 s; on upstream_errors.parcel: timeout (notice section_missing; the basic package is charged once, the repeat is free within the dedup window) request again after a few seconds with a new Idempotency-Key.
• Error paths. 422 capakey_invalid (wrong form or more than 10 keys; details[] names the wrong parts); 422 capakey_too_far (a parcel more than 2 km from the address; nothing delivered or charged). The parcel section is part of the basic package, so capakeys needs no extra section. A capakey that does not exist in the parcel plan: notice capakey_not_found (section parcel) and parcels_not_found[]; the other parcels are delivered. When the parcel analysis fails for one parcel, only its cadastral area counts (notice parcel_analysis_incomplete).
• Load. Keep to the parcels of the case. Every request with capakeys does one cadastre query plus one parcel analysis per parcel (up to 10); a farm with 3 parcels takes 3 to 12 s.

Worked example with real responses (Rijselstraat 62, Ieper): integration guide, section 3.

Land (type=land) 2.5.0

type=land (aliases grond, terrain, bouwgrond) requests the bundle for a building plot. What changes compared to a house or apartment:

• Comparables: one block (type: land, transaction: sale, no rent block) with land listings for sale (building plots, project land and land without a more precise subtype; agricultural land, meadows, woodland, orchards, industrial and business land, parking spaces, garages and recreational land are excluded on the basis of the advertised subtype) of all publication years (2.5.1: no age limit, so that you can adjust the asking prices of older listings for the market evolution within the case (price indexation); the licence terms remain: no merging, indexing or storing across cases), within 5 km of the address; with fewer than 10 in total the radius is extended once to 10 km (radius_m). Ranking: the listings of the last 24 months first (sorted by distance), then the older ones (sorted by distance), at most 25 per block; every item carries age_months (whole calendar months between published and today) and the block field max_age_months is null for land. Still fewer than 10: block field low_sample: true and notice low_sample (section basic). Each item carries the usual fields where they make sense (address, distance_m, price, price_kind, source, published, status, history, photos, thumbnail, photo_count) plus plot_area_m2 and price_per_m2_plot (asking price per m² of plot); the housing fields (living_area_m2, price_per_m2, bedrooms, epc_label, year_built, condition, building_type, new_build) are null. features is limited to {plot_area_m2, zoning, flood_zone, land_type} (zoning is currently always null: the zoning of a listing is not looked up; the zoning of the subject parcel is in parcel.zoning; land_type is building_plot, project_land or other and drives the first word of summary: "Building plot", "Development land" or "Land"). summary reads for example "Building plot of 694 m² in Kluisbergen, listed since 10-09-2026."
• Neighbourhood: land_price_level (see above) from the same land listings (same exclusions) of the last 24 months; a price level must be current, so with fewer than 10 usable listings within 24 months the window is widened to 60 months and max_age_months says which window was used (24 or 60; 2.5.1); only listings with a plot area and an asking price between 15 and 5,000 EUR per m² of plot enter the quartiles (count), so that agricultural land advertised as buildable and placeholder areas do not distort the level (items outside that band stay in the list with their own price_per_m2_plot); price_level and epc_prices are null with notice housing_stats_not_available_for_land; building_stock, safety and amenities as usual.
• No AVM: Taxon delivers no automated valuation and no indicative land value for land. sections=basic,avm stays HTTP 200: avm is null and not in sections_delivered, notice {code: avm_not_available_for_land, section: avm}, the AVM option is not charged. living_area_m2 may be omitted.
• Parcel and price map: unchanged. The parcel section (zoning, pre-emption right, several parcels via capakeys) is the core for land; price_map stays the housing map (asking prices per m² of houses and apartments per neighbourhood), not a land price map.
• Billing: the basic package as usual (one price per case, dedup 30 days, pilot and test key as for houses); no AVM option.

Coverage (15-09-2026, listings of the last 24 months with a price; on 16-09-2026 across all publication years about 73,000 land listings, of which about 38,200 within 24 months): Flanders about 30,800 land listings, Wallonia about 8,300, Brussels about 330; about 95 % carry a plot area. Some rural Walloon municipalities have few land listings (then low_sample).

Example: live response of 15-09-2026 with a test key (Accept-Language: en, request f0c372798b3f285b66ab4b584819be57; the 2.5.1 fields age_months and max_age_months: null added), shortened to one comparable with one photo, the main parcel fields and the neighbourhood blocks that change for land; building_stock, safety, amenities, parcels, parcel_candidates and price_map are replaced by "...":

{
  "request_id": "f0c372798b3f285b66ab4b584819be57",
  "environment": "test",
  "address": {
    "input": "Buissestraat 17, 9690 Kluisbergen",
    "normalized": "Buissestraat 17, 9690 Kluisbergen",
    "box": null,
    "postal_code": "9690",
    "municipality": "Kluisbergen",
    "lat": 50.76716,
    "lon": 3.484313,
    "region": "VL",
    "nis_code": "45060",
    "geocoder": "geo.api.vlaanderen.be",
    "geocode_score": 0.95,
    "precision": "house_number"
  },
  "sections_delivered": [
    "basic",
    "parcel",
    "price_map"
  ],
  "basic": {
    "comparables": [
      {
        "type": "land",
        "type_label": "land",
        "transaction": "sale",
        "transaction_label": "for sale",
        "address_mode": "house_number",
        "radius_m": 5000,
        "count": 25,
        "excluded_subject_property": 0,
        "max_age_months": null,
        "low_sample": false,
        "items": [
          {
            "ref": "r_9965f5493e",
            "address": "Buissestraat 19, 9690 Kluisbergen",
            "distance_m": 25,
            "type": "land",
            "transaction": "sale",
            "price": 80000,
            "price_kind": "asking_price",
            "price_kind_label": "asking price",
            "price_per_m2": null,
            "price_per_m2_plot": 115,
            "living_area_m2": null,
            "plot_area_m2": 694,
            "bedrooms": null,
            "epc_label": null,
            "epc_kwh_m2": null,
            "epc_source": null,
            "year_built": null,
            "condition": null,
            "building_type": null,
            "new_build": null,
            "published": "2026-09-10",
            "days_online": 4,
            "last_seen": "2026-09-14",
            "age_months": 0,
            "status": "online",
            "status_label": "online",
            "source": "listing",
            "source_label": "listing",
            "features": {
              "plot_area_m2": 694,
              "zoning": null,
              "flood_zone": null,
              "land_type": "building_plot"
            },
            "summary": "Building plot of 694 m² in Kluisbergen, listed since 10-09-2026.",
            "thumbnail": {
              "url": "https://taxonapi.be/api/v1/marketexplorer/foto/fp_WzI3NDc1OTEsIjAxYTA0NzM2LTE5OGUtN2Q3ZC1iZjNjLWYyZDQ2NzliOTI3ZSIsMTc4OTQ2MzYyNiwicCJd.QB9ILrzzIwQxlyOV?w=160",
              "valid_until": "2026-09-15T09:13:46Z"
            },
            "photo_count": 13,
            "history": [
              {
                "date": "2026-08-28",
                "price": 80000,
                "event": "published",
                "label": "published"
              }
            ],
            "photos": [
              {
                "url": "https://taxonapi.be/api/v1/marketexplorer/foto/fp_WzI3NDc1OTEsIjAxYTA0NzM2LTE5OGUtN2Q3ZC1iZjNjLWYyZDQ2NzliOTI3ZSIsMTc4OTQ2MzYyNiwicCJd.QB9ILrzzIwQxlyOV?w=640",
                "download_token": "b17f02c8feb98b013e60",
                "valid_until": "2026-09-15T09:13:46Z"
              }
            ]
          }
        ]
      }
    ],
    "neighbourhood": {
      "sector": {
        "code": "45060A010",
        "name": "BUISESTRAAT",
        "level": "sector",
        "municipality": "Kluisbergen"
      },
      "building_stock": "...",
      "price_level": null,
      "epc_prices": null,
      "safety": "...",
      "land_price_level": {
        "radius_m": 5000,
        "count": 116,
        "price_per_m2_plot": {
          "p25": 126,
          "median": 160,
          "p75": 224
        },
        "price_kind": "asking_price",
        "max_age_months": 24
      }
    },
    "amenities": "..."
  },
  "parcel": {
    "capakey": "45043C0460/00X000",
    "region": "VL",
    "area_m2": 528.79,
    "cadastral_area_m2": 528.78,
    "fiscal_situation": "2027-01-01",
    "zoning": {
      "category": "residential",
      "label": "woongebieden",
      "plan": "gewestplan"
    },
    "preemption_right": {
      "status": "none",
      "source": "RVV thematic layer, right of pre-emption (Flanders)"
    },
    "source": "CadGIS PlanParcellaire (FPS Finance) / GRB Gbg - building at ground level (Digitaal Vlaanderen)",
    "main_parcel": "45043C0460/00X000",
    "parcels_count": 1,
    "total_area_m2": 528.79,
    "plot_area_source": "cadastre_main_parcel",
    "parcels": "...",
    "parcel_candidates": "..."
  },
  "avm": null,
  "price_map": "...",
  "billing": {
    "user_ref": "office-oudenaarde-02",
    "case_ref": "DOS-2026-0518",
    "charged": false,
    "pilot": false,
    "free_reason": "test",
    "price": {
      "package": 0.0,
      "avm": 0.0,
      "total": 0.0,
      "currency": "EUR",
      "excl_vat": true
    },
    "dedup_of": null,
    "dedup_valid_until": "2026-10-15T10:13:47+02:00",
    "month": "2026-09",
    "month_to_date": {
      "cases": 0,
      "amount": 0.0
    },
    "pilot_status": {
      "active": true,
      "quota": 200,
      "used": 0,
      "remaining": 200,
      "ends": "2026-11-03",
      "expired": false
    },
    "today": {
      "client_today": 10,
      "user_today": 1
    }
  },
  "notices": [
    {
      "code": "avm_not_available_for_land",
      "section": "avm",
      "message": "AVM not delivered: Taxon does not provide an automated valuation for land (type land); not charged."
    },
    {
      "code": "housing_stats_not_available_for_land",
      "section": "basic",
      "message": "price_level and epc_prices are housing statistics and are not delivered for land; see neighbourhood.land_price_level."
    },
    {
      "code": "price_map_sparse",
      "section": "price_map",
      "message": "price map: fewer than 30 listings in the subject neighbourhood (small sample)."
    },
    {
      "code": "test_environment",
      "section": null,
      "message": "test key: not invoiced"
    }
  ],
  "upstream_errors": {},
  "attribution": "References: Taxon (taxon.be)",
  "disclaimer": "Asking prices from listings, not notarial sale prices. Data for internal use per case only; building a derived database is prohibited. The valuer decides, the AVM is a support tool.",
  "generated_at": "2026-09-15T10:13:47+02:00"
}

Price map (section price_map) 2.0

Asking-price levels per neighbourhood within radius_m (3,000 m) of the address, sorted by distance, at most 40 neighbourhoods (the subject neighbourhood always included), delivered as data plus GeoJSON geometry. Taxon delivers no map images or tiles: you draw the polygons yourself with your own map library and licence (for example Leaflet, MapLibre or Mapbox) and colour them by price_per_m2_house or price_per_m2_apartment. Part of the basic package since 2.4.0: no separate price (the package price is in billing.price.package); dedup follows the package. Block size 20 to 50 KB; warm response under 0.5 s, the first request after a service restart can take up to 20 s. Measured live on 07-09-2026: Braine-l'Alleud 40 neighbourhoods, Ieper 38, Schaerbeek 40.

Notice price_map_sparse (section price_map) when the subject neighbourhood itself has fewer than 30 listings; the section is still delivered. When no neighbourhood with prices lies within 3 km the section is null, the notice price_map_unavailable is added, upstream_errors.price_map is no_coverage; this is no failure and the basic package stays charged. Do not store the geometry beyond the case (usage rules, section 11). Real example: live response of 08-09-2026 (live key, sections=basic, Grote Markt 34, 8900 Ieper, request f5569dd2c231469abaa2536b1bc4dd61), 2 of the 38 neighbourhoods, geometry of the subject neighbourhood complete:

"price_map": {
  "radius_m": 3000,
  "price_kind": "asking_price",
  "reference_period": "2026-03-30",
  "updated_at": "2026-07-09T10:26:08+00:00",
  "subject_neighbourhood": "7220",
  "source": "Taxon asking prices (advertised prices, not notarial sale prices)",
  "neighbourhoods": [
    {
      "id": "7220",
      "name": "Ieper-Centrum",
      "municipality": "Ieper",
      "postal_code": "8900",
      "distance_m": 0,
      "is_subject": true,
      "price_per_m2_house": 1937.91,
      "price_per_m2_apartment": 2693.77,
      "listings_count_house": 76,
      "listings_count_apartment": 59,
      "low_sample": false,
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[2.89239, 50.84819], [2.89082, 50.84804], [2.88999, 50.84756], [2.88856, 50.84716], [2.88727, 50.84885], [2.88559, 50.84838], [2.88386, 50.84823], [2.88343, 50.84899], [2.88207, 50.8487], [2.88188, 50.84888], [2.88017, 50.8484], [2.87996, 50.84875], [2.87954, 50.84865], [2.87908, 50.84969], [2.87869, 50.84955], [2.87772, 50.85146], [2.88352, 50.85238], [2.88367, 50.85225], [2.88646, 50.85268], [2.88857, 50.85268], [2.89005, 50.85297], [2.89134, 50.853], [2.89214, 50.85059], [2.89239, 50.84819]]]
      }
    },
    {
      "id": "7226",
      "name": "Diksmuidse Poort",
      "municipality": "Ieper",
      "postal_code": "8900",
      "distance_m": 121,
      "is_subject": false,
      "price_per_m2_house": 1991.52,
      "price_per_m2_apartment": 2374.19,
      "listings_count_house": 41,
      "listings_count_apartment": 22,
      "low_sample": false,
      "geometry": {"type": "Polygon", "coordinates": ["…"]}
    }
  ]
}

Per region

Flood data comes in a later version as an extra field in the parcel section. Until then the valuer consults the flood data at the region; the API makes no statement about it.

6.Dedup (free repetition) and Idempotency-Key

Billing happens per user + property. The property is determined by the geocode (rounded to about 1 m), not by the literal spelling of the address. A charged request stays valid for 30 days for the same user. A property is the geocoded point plus the box number; another type, other AVM parameters, other capakeys or another language do not make another property: such a repeat is rebuilt with the new input and stays free for the sections already delivered (dedup freezes nothing).

Mind the watchdog: when one X-User-Ref carries an unnaturally large share of the traffic, or a user shows a grid-scan pattern (consecutive house numbers or postal codes in a short time), that user is suspended (403 user_suspended); the other users keep working. The suspension hits the user, not the client (your key); only with three or more suspended users within 24 hours 403 client_suspended follows. So always use the real user id.

7.Caps and error codes

Caps

Every 200 response shows the daily count in billing.today (client_today, user_today), so that you can see a cap coming. Dedup repetitions count as traffic too.

Retry advice. On 429: wait for Retry-After (or retry_after from the body when the header is missing, the nginx variant) and retry with the same Idempotency-Key. On 502, 503, 504 or 500: at most 3 attempts with exponential back-off (2, 4, 8 s; for 503 the Retry-After value), same Idempotency-Key. On 403 quota_exceeded: wait for Retry-After (until midnight). On other 4xx: do not retry, the request itself is wrong.

Error codes

Uniform error body: {"error": "...", "message": "...", "request_id": "...", "charged": false}, possibly completed with details[] ({field, issue}), retry_after, scope and limit, section, user_ref, reason, since or pilot. message follows Accept-Language.

No error is ever charged (charged: false).

8.GET /usage

Your own usage per calendar month: total, per user, per API key (2.4.1), per day, per section and a quality block (error percentage, latency p50/p95, number of requests with upstream failures). requests counts all requests, cases the requests with HTTP 200, charged those with a price; sections counts charged units with the keys package (basic package) and avm (AVM option); sections_delivered (since 2.4.0 also in total) counts the four real sections basic, parcel, avm, price_map; per_section uses package and avm. Meant to check yourself what Taxon invoices and to re-invoice your users. X-User-Ref is optional here and works as a filter. The block plan shows your plan without prices: sections_allowed, max_per_minute, max_per_day, max_per_user_per_day, test_max_per_day, dedup_days, idempotency_hours, address_mode. requests counts the same requests as the daily caps (see 7).

Unknown parameters (including the 1.x names maand, formaat, gebruiker_ref) give 400 invalid_request with details[].field. Live response of 08-09-2026 (live key, two users, two keys, four requests; the client code is replaced by a placeholder):

GET /api/v1/partner/usage?month=2026-09 HTTP/1.1
X-Api-Key: tx_live_<32 hex>

{
  "client": "<client code>",
  "month": "2026-09",
  "environment": "live",
  "user_ref": null,
  "total": {
    "requests": 4,
    "cases": 4,
    "charged": 4,
    "free_dedup": 0,
    "free_pilot": 0,
    "free_error": 0,
    "sections": {"package": 3, "avm": 2},
    "sections_delivered": {"basic": 4, "parcel": 4, "avm": 2, "price_map": 4},
    "amount": 13.0,
    "currency": "EUR",
    "excl_vat": true,
    "duration_ms_avg": 3531
  },
  "per_user": [
    {
      "user_ref": "office-kortrijk-03",
      "requests": 2,
      "cases": 2,
      "charged": 2,
      "free_dedup": 0,
      "sections": {"package": 2, "avm": 1},
      "sections_delivered": {"basic": 2, "parcel": 2, "avm": 1, "price_map": 2},
      "amount": 8.0,
      "last_activity": "2026-09-08T10:39:27+02:00"
    },
    {
      "user_ref": "office-ieper-01",
      "requests": 2,
      "cases": 2,
      "charged": 2,
      "free_dedup": 0,
      "sections": {"package": 1, "avm": 1},
      "sections_delivered": {"basic": 2, "parcel": 2, "avm": 1, "price_map": 2},
      "amount": 5.0,
      "last_activity": "2026-09-08T10:39:16+02:00"
    }
  ],
  "per_day": [{"day": "2026-09-08", "requests": 4, "cases": 4, "charged": 4, "amount": 13.0}],
  "per_section": {"package": {"delivered": 4, "charged": 3, "amount": 9.0}, "avm": {"delivered": 2, "charged": 2, "amount": 4.0}},
  "quality": {"error_pct": 0.0, "latency_p50_ms": 3065, "latency_p95_ms": 7531, "upstream_errors": 0},
  "pilot": null,
  "generated_at": "2026-09-08T10:39:27+02:00",
  "plan": {
    "sections_allowed": ["basic", "parcel", "avm", "price_map"],
    "max_per_minute": 30,
    "max_per_day": 300,
    "max_per_user_per_day": 80,
    "test_max_per_day": 80,
    "dedup_days": 30,
    "idempotency_hours": 24,
    "address_mode": null
  },
  "request_id": "c535faa3301644c1af51f3901fea7e2c"
}

The block pilot (and billing.pilot_status) is only the pilot counter. The client status from the ledger (pilot, active, suspended, ended) is not delivered in the response; you notice a suspension by 403 client_suspended or 403 user_suspended. With a live key sections and charged carry the charged counts and amount the amounts according to your agreement.

Per API key 2.4.1

Since 2.4.1 the response also carries the block per_key (between per_user and per_day): the usage per API key, with the same filters as the rest of the response (month, the environment of the calling key, user_ref). Per key: prefix (the first 12 characters, as in your key list), label (null when empty), environment, active, revoked_at (null while active), requests, cases, charged, sections, sections_delivered, amount and last_activity; sorted by amount, then requests, descending. Keys without requests in the month are not listed; a revoked key with requests in the month is (active: false, revoked_at filled in). The sums over per_key equal total. For the example above (three requests with the current live key, one with a previous live key that was revoked since):

"per_key": [
  {
    "prefix": "tx_live_3f9a",
    "label": "production",
    "environment": "live",
    "active": true,
    "revoked_at": null,
    "requests": 3,
    "cases": 3,
    "charged": 3,
    "sections": {"package": 2, "avm": 2},
    "sections_delivered": {"basic": 3, "parcel": 3, "avm": 2, "price_map": 3},
    "amount": 10.0,
    "last_activity": "2026-09-08T10:39:27+02:00"
  },
  {
    "prefix": "tx_live_b71c",
    "label": "old key",
    "environment": "live",
    "active": false,
    "revoked_at": "2026-09-08T10:39:20+02:00",
    "requests": 1,
    "cases": 1,
    "charged": 1,
    "sections": {"package": 1, "avm": 0},
    "sections_delivered": {"basic": 1, "parcel": 1, "avm": 0, "price_map": 1},
    "amount": 3.0,
    "last_activity": "2026-09-08T10:39:15+02:00"
  }
]

CSV

?format=csv delivers one row per request, UTF-8 with BOM, separator ;, every field in double quotes, decimal , (opens directly in Excel nl-BE/fr-BE), CRLF line ends. File name taxon-usage-<client>-<month>.csv (Content-Disposition). This is the same list as the usage attachment of the monthly invoice. Sections are separated with |; charged is 0 or 1. Real rows of 08-09-2026 (the four requests of the usage example above, 16 columns since 2.4.1): row 1 is the basic package for Grote Markt 34 Ieper, row 2 the AVM option added one second later for the same case (dedup_of = row 1, package 0), row 3 the main example of section 4, row 4 a request with sections=parcel normalised to the package:

"request_id";"timestamp";"user_ref";"case_ref";"address";"region";"sections_requested";"sections_delivered";"charged";"free_reason";"dedup_of";"price_package";"price_avm";"price_total";"status_code";"key_prefix"
"f5569dd2c231469abaa2536b1bc4dd61";"2026-09-08T10:39:15+02:00";"office-ieper-01";"DOS-2026-0451";"Grote Markt 34, 8900 Ieper";"VL";"basic|parcel|price_map";"basic|parcel|price_map";"1";"";"";"3,00";"0,00";"3,00";"200";"tx_live_b71c"
"76cddf8bb6fc4a299283f85aa2be799e";"2026-09-08T10:39:16+02:00";"office-ieper-01";"DOS-2026-0451";"Grote Markt 34, 8900 Ieper";"VL";"basic|parcel|avm|price_map";"basic|parcel|avm|price_map";"1";"";"f5569dd2c231469abaa2536b1bc4dd61";"0,00";"2,00";"2,00";"200";"tx_live_3f9a"
"cf514c7de2714c11806e2ebf053d0247";"2026-09-08T10:39:24+02:00";"office-kortrijk-03";"DOS-2026-0452";"Doorniksestraat 40, 8500 Kortrijk";"VL";"basic|parcel|avm|price_map";"basic|parcel|avm|price_map";"1";"";"";"3,00";"2,00";"5,00";"200";"tx_live_3f9a"
"3aa7ba378561487fad54fd5fbbe83f1e";"2026-09-08T10:39:27+02:00";"office-kortrijk-03";"";"Rijselstraat 20, 8900 Ieper";"VL";"basic|parcel|price_map";"basic|parcel|price_map";"1";"";"";"3,00";"0,00";"3,00";"200";"tx_live_3f9a"

free_reason is empty (charged) or dedup, pilot, pilot_exhausted (row with status 403: the request got pilot_exhausted), test, no_result (zero comparables, or an address error: rows with status 404 or 422), error, timeout. price_package is the price of the basic package (basic + parcel + price_map), price_avm that of the AVM option (columns since 2.4.0; the three former per-section price columns have disappeared). sections_requested is the normalised list: the package written out as basic|parcel|price_map. key_prefix (last column, 2.4.1) is the prefix of the API key that made the request, as in per_key[].prefix.

9.GET /health

Public, without key, without data. Suitable for your monitoring. The keys of this endpoint are deliberately kept from 1.x (Dutch names): versie = version, tijd = time, bundel = bundle mode, db = database.

{"status": "ok", "service": "taxon-partner-api", "versie": "2.5.1", "tijd": "2026-09-16T10:47:16+02:00", "bundel": "live", "db": "ok"}

versie is the version of the service (2.4.1 = contract 2.0 plus the price_map section, the comparable features, the fixes of the first external integration test, key management by the partner, the basic package usage per key and, since 2.4.2, the current cadastral parcel plan with fiscal_situation), not the version of this contract (2.0). bundel is live (real sections) or stub (test set-up); db is ok or fout (error). On a database error the endpoint answers HTTP 503 with "status": "degraded". There is no separate maintenance flag; planned maintenance is announced by e-mail.

10.Attribution and disclaimer (required)

Every screen, report or document showing API data carries visibly and inseparably the attribution and the disclaimer. The API delivers both literally in the fields attribution and disclaimer, in the language of Accept-Language. They may not be shortened, moved to an annex or removed.

Source lines per data layer

Next to the general attribution the API delivers per layer a source line (source, attribution) that you also copy next to that data, also in white-label:

• Parcel and building stock: Source: FPS Finance, cadastral parcel plan (CadGIS) plus the regional buildings layer named in parcel.source
• Statistical sectors and indexes: Source: Statbel, CC BY 4.0
• Wallonia (zoning, geocoding): Source: Service public de Wallonie
• Flanders: Source: Flemish government, Free Open Data Licence v1.2
• Brussels: Source: perspective.brussels / Brussels Environment, CC BY
• Safety: Source: Federal Police, police crime statistics (PCS)
• Amenities: © OpenStreetMap contributors (ODbL)
• Price map: the source line of the section

Additional qualifications that you copy literally into your report templates: the comparables are asking prices from public supply, not transaction prices; the AVM value is an indicative model output with a range, not an appraisal; parcel, plan and government data are delivered "as is" and for information only with their reference date; the data contains no energy performance data (EPC/PEB).

11.Usage rules

Summary of the contractual rules that the API also enforces technically. The agreement prevails.

• Per case. Show the data only to the valuer and include it only in the valuation report of the case for which the request was made. Every request belongs to a concrete case and an identified user (X-User-Ref, preferably also X-Case-Ref).
• Retention at most 30 days. Raw API responses disappear from operational systems, logs and caches at the latest 30 days after the request. Only the finished report (PDF) stays in the legal case archive.
• No derived database. Do not merge, index or store data from several requests into your own database, map layer, index or price model; this includes the price-map geometry.
• No model feeding. Do not use the data to train, calibrate, validate or improve an algorithm, model or AI system.
• No resale or bulk. Do not resell, publish, export or hand over to third parties outside the report; do not query the API automatically or systematically outside a case.
• Photos (2.5.0). Fetch photos within the validity of the link (1 hour) and use them only for the case for which the request was made. Embedding them in the valuation report (PDF) of that case is allowed, always with a visible source line next to every photo (attribution, see 10), subject to the partner agreement (the partner indemnifies Taxon against claims of portals or agents concerning the photos). No republication, no storage outside that report, no bulk download; the resolution stays at most 640 px.
• Attribution visible in your UI and in every report (see 10). White-label only through a separate addendum.
• EPC "as advertised". Never show EPC labels of comparables as a looked-up or verified value.
• No notarial prices. Never communicate that the data comes from notaries, VLABEL or transactions; they are asking prices.
• Human decision. No decision with legal effect (credit, tax, insurance) solely on the basis of the API or the AVM without the final responsibility of an expert.
• Key secret, report a leak within 48 hours; on request (at most twice a year) provide an extract of case numbers against requests.
• Documentation confidential. This documentation is meant for your technical staff; do not publish it.

12.Changelog and 1.x mapping

Changes to existing fields are announced at least 30 days in advance; new fields can be added without notice (your parser must ignore unknown fields). A new major version gets a new path (/api/v2/partner/).

Mapping 1.x (Dutch) to 2.0 (English)

For teams that read the 1.x documentation. The old names no longer work, except the three header aliases. Keys not listed (lat, lon, capakey, epc_label, score, label, plan, model, n, p25, p75, pct, ref, url, download_token, quota, code, status, type, request_id, pilot, details, top_10, comparables, parcel, avm, capakeys, epc, format) are unchanged.

13.Contact