openapi: 3.2.0
info:
  title: flatin.pt Public API
  summary: 'Portuguese property taxes, machine-readable: IMT and stamp duty (Imposto do Selo) on a purchase, IMI rates for all 308 municipalities.'
  description: 'Keyless public API of flatin.pt. Numbers are the same as on the site and come from the official tables; every successful JSON answer carries an attribution field — show it next to the numbers. Rate limits: 120 requests per minute per IP address, HTTP 429 with Retry-After when exceeded. Status: https://flatin.pt/status/. MCP server: https://flatin.pt/mcp.'
  termsOfService: https://flatin.pt/en/legal/termos-utilizacao/
  contact:
    name: flatin.pt
    url: https://flatin.pt/en/tools/api-and-data/
    email: info@flatin.pt
  license:
    name: CC BY 4.0 (data)
    url: https://creativecommons.org/licenses/by/4.0/
  version: 1.0.0
servers:
- url: https://flatin.pt
tags:
- name: Public
  description: 'Keyless public endpoints: IMI rates and IMT calculation.'
paths:
  /api/v1/imi/rates:
    get:
      tags:
      - Public
      summary: IMI rates for all municipalities
      description: 'The yearly urban IMI rate of every Portuguese municipality for the latest verified tax year, or for `year` if given. Where a municipality sets no single rate (it is set per parish), the rate comes with `available: false` and the reason, never as zero. Every answer carries an `attribution` field.'
      operationId: imi_rates_api_v1_imi_rates_get
      parameters:
      - name: year
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Year
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/imi/rates.csv:
    get:
      tags:
      - Public
      summary: The same rates as one CSV file
      description: 'Open data: the same rows as the JSON list, under the same licence (see the Link header). An empty rate cell means the municipality sets no single rate, not zero. `year` selects a verified past table.'
      operationId: imi_rates_csv_api_v1_imi_rates_csv_get
      parameters:
      - name: year
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Year
      responses:
        '200':
          description: CSV file
          content:
            text/csv: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/imi/rates/{codigo}:
    get:
      tags:
      - Public
      summary: IMI rate of one municipality
      description: One municipality by its four-digit code or name, with the rate `history` by tax year and its `movement` (raised, lowered, unchanged, returned, not_comparable). An unknown municipality gets 404 with a link to the full list.
      operationId: imi_rate_api_v1_imi_rates__codigo__get
      parameters:
      - name: codigo
        in: path
        required: true
        schema:
          type: string
          description: Four-digit municipality code (1312) or its name (Porto)
          title: Codigo
        description: Four-digit municipality code (1312) or its name (Porto)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/imt/calculate:
    post:
      tags:
      - Public
      summary: What a purchase costs on top of the price
      description: 'IMT (property transfer tax), Imposto do Selo (stamp duty) and an estimate for the deed and registration. Body: `value` (price in euros), optional `territory` (`continente` or `regioes_autonomas`), `primary_home` (default true) and `buyer_is_young` (35 or under, default false). Invalid input gets 422 with `error` and `field`.'
      operationId: imt_calculate_api_v1_imt_calculate_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError