madeira.fun Hiking Permits

List the Madeira trails that need a government hiking permit for a set start time and can be reserved on madeira.fun. Returns each trail's seo_slug (use it in the other tools), code (such as PR 18 or PS PR 1), name, island, official trail status, trail page and day feed links. Optional query filters by code or name, accents ignored.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 120,
      "description": "Optional filter: a code such as \"PR 18\" or a name such as \"Pico Ruivo\"."
    }
  },
  "additionalProperties": false
}

Day-by-day permit availability for one trail, from today up to 119 days ahead (Madeira dates). Each day is open (start times left for visitors), full (sold out for visitors), started (today only: every start time has already begun, nothing is left to book today; not sold out), closed, no_times (no start times listed) or unknown (not checked yet), with permits left for visitors and when it was last checked. Use date for one day, or from and to for a range; the default is the next 7 days. For the start times of a day, use get_start_times.

{
  "type": "object",
  "properties": {
    "trail": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The trail: its seo_slug from list_permit_trails (preferred), a code such as \"PR 18\", \"PR18\" or \"PS PR1\", or a name such as \"Levada do Rei\". Accents are ignored."
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "One day (YYYY-MM-DD, a Madeira calendar date)."
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day of a range (YYYY-MM-DD, a Madeira calendar date)."
    },
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last day of a range (YYYY-MM-DD, a Madeira calendar date)."
    }
  },
  "required": [
    "trail"
  ],
  "additionalProperties": false
}

Give trail (required without a partner key). The start times of a trail with the permits left for visitors at each one (as the trail page shows them: a number from 6 up, "few" at 1 to 5, "full" at 0), and a book_url per open start time that opens Reserve on madeira.fun at that time. Today up to 119 days ahead: give trail and date, or from and to (up to 14 days per call). Further ahead, up to 365 days: one trail and one date per call. Start times that have already begun today are never listed. Rate limited; a partner key (Authorization: Bearer mfk_...) gives higher limits, longer ranges and every trail at once (omit trail).

{
  "type": "object",
  "properties": {
    "trail": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The trail: its seo_slug from list_permit_trails (preferred), a code such as \"PR 18\", \"PR18\" or \"PS PR1\", or a name such as \"Levada do Rei\". Accents are ignored. Required, except for a partner key asking for every trail."
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "One day (YYYY-MM-DD, a Madeira calendar date)."
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day of a range (YYYY-MM-DD, a Madeira calendar date)."
    },
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last day of a range (YYYY-MM-DD, a Madeira calendar date)."
    }
  },
  "additionalProperties": false
}

The government hiking permit fee records in force today (format MF-PRC-1.0, the same records as https://madeira.fun/hiking/permit-data), with legal references and exemptions. Give trail to get the fee that applies to that trail. The fee is paid to the government, never to madeira.fun.

{
  "type": "object",
  "properties": {
    "trail": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Optional. The trail: its seo_slug from list_permit_trails (preferred), a code such as \"PR 18\", \"PR18\" or \"PS PR1\", or a name such as \"Levada do Rei\". Accents are ignored."
    }
  },
  "additionalProperties": false
}

Build the link a visitor opens to book a permit: https://madeira.fun/hiking/<seo_slug>?date=YYYY-MM-DD opens that date's start times on the trail page. Optional adults (visitors aged 13 or over who are not Madeira residents) and children (aged 12 or under, no fee) preset the party; lang sets the page language. The link books and stores nothing. On the page the visitor picks a start time and presses Reserve: madeira.fun submits the government reservation for them and emails a PayPay link to pay the government fee.

{
  "type": "object",
  "properties": {
    "trail": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The trail: its seo_slug from list_permit_trails (preferred), a code such as \"PR 18\", \"PR18\" or \"PS PR1\", or a name such as \"Levada do Rei\". Accents are ignored."
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "The hike date (YYYY-MM-DD, a Madeira calendar date)."
    },
    "adults": {
      "type": "integer",
      "minimum": 0,
      "maximum": 60,
      "description": "Visitors aged 13 or over who are not Madeira residents (they pay the government fee)."
    },
    "children": {
      "type": "integer",
      "minimum": 0,
      "maximum": 60,
      "description": "Visitors aged 12 or under who are not Madeira residents (no fee, still part of the reservation)."
    },
    "lang": {
      "type": "string",
      "enum": [
        "en",
        "pt",
        "es",
        "de",
        "fr",
        "ru",
        "lv",
        "it",
        "pl",
        "ro",
        "nl",
        "cs",
        "da",
        "sv",
        "no",
        "fi",
        "hu",
        "tr"
      ],
      "description": "Page language."
    }
  },
  "required": [
    "trail",
    "date"
  ],
  "additionalProperties": false
}

Step 1 of 2 to reserve a Madeira hiking permit for a visitor through madeira.fun. Before calling, tell the visitor these three points in your own words and get their yes: (1) madeira.fun creates a madeira.fun account with the visitor's email address (or signs in the one they already have). (2) madeira.fun sends that email address and the party size to the Madeira government's Simplifica system (IFCN), which issues the permit. The name stays with madeira.fun. (3) Reserving is not paying: the government's PayPay payment link arrives by email, and the visitor must pay the permit fee to the government within 24 hours, or before the start time if that is sooner, or the reservation lapses. madeira.fun charges nothing and never collects the permit fee. This step checks the start time and emails the visitor a 6-digit code from madeira.fun; nothing is reserved yet. Then ask the visitor for the code and call confirm_reservation. Standard visitor reservations only (no Madeira residents, no Verified Permit): for those use build_booking_link. Today up to 119 days ahead. At most 3 codes per email per hour. For apps calling from a server: a call from a web page is refused.

{
  "type": "object",
  "properties": {
    "trail": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The trail: its seo_slug from list_permit_trails (preferred), a code such as \"PR 18\", \"PR18\" or \"PS PR1\", or a name such as \"Levada do Rei\". Accents are ignored."
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "The hike date (YYYY-MM-DD, a Madeira calendar date)."
    },
    "start_time": {
      "type": "string",
      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
      "maxLength": 5,
      "description": "The begin of an open start time from get_start_times, HH:MM (Madeira time)."
    },
    "adults": {
      "type": "integer",
      "minimum": 0,
      "maximum": 60,
      "description": "Visitors aged 13 or over who are not Madeira residents (each pays the government fee)."
    },
    "children": {
      "type": "integer",
      "minimum": 0,
      "maximum": 60,
      "description": "Visitors aged 12 or under who are not Madeira residents (no fee, still part of the reservation)."
    },
    "name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 80,
      "description": "The visitor's name, for their madeira.fun reservation (madeira.fun keeps it; the government gets the email and the party size)."
    },
    "email": {
      "type": "string",
      "maxLength": 254,
      "description": "The visitor's email: madeira.fun sends the code there, creates or signs in their madeira.fun account with it, and the government's payment link and permit go there. Not an Apple Hide My Email address."
    },
    "lang": {
      "type": "string",
      "enum": [
        "en",
        "pt",
        "es",
        "de",
        "fr",
        "ru",
        "lv",
        "it",
        "pl",
        "ro",
        "nl",
        "cs",
        "da",
        "sv",
        "no",
        "fi",
        "hu",
        "tr"
      ],
      "description": "Language of madeira.fun's emails (default en)."
    },
    "visitor_agreed": {
      "type": "boolean",
      "description": "true only after the visitor heard the three points in this tool's description and said yes. The emailed code is what confirms it."
    }
  },
  "required": [
    "trail",
    "date",
    "start_time",
    "name",
    "email",
    "visitor_agreed"
  ],
  "additionalProperties": false
}

Step 2 of 2: with the code the visitor got by email, madeira.fun signs them in, checks the start time live and submits the government reservation for exactly what start_reservation described. The answer gives order_id and status_token. The reservation is not paid: madeira.fun then emails the government's PayPay link, and the visitor must pay the permit fee to the government within 24 hours, or before the start time if that is sooner, or it lapses. Safe to retry: calling it again with the same reservation_token returns the same order and never books twice (also after a lost answer). At most 5 reservations per email per day through apps.

{
  "type": "object",
  "properties": {
    "reservation_token": {
      "type": "string",
      "maxLength": 3000,
      "description": "The reservation_token start_reservation returned, unchanged."
    },
    "code": {
      "type": "string",
      "maxLength": 12,
      "description": "The code from the madeira.fun email, digits only."
    }
  },
  "required": [
    "reservation_token",
    "code"
  ],
  "additionalProperties": false
}

Where a reservation made with confirm_reservation stands: being reserved, waiting for payment (with the government's PayPay link, the amount and the deadline), paid, not taken, cancelled or lapsed. Needs order_id and status_token from confirm_reservation.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "maxLength": 36,
      "description": "order_id from confirm_reservation."
    },
    "status_token": {
      "type": "string",
      "maxLength": 200,
      "description": "status_token from confirm_reservation."
    }
  },
  "required": [
    "order_id",
    "status_token"
  ],
  "additionalProperties": false
}