{
 "openapi": "3.1.0",
 "info": {
  "title": "Fair Fare",
  "version": "1.0.0",
  "description": "Fair Fare is a neutral fare check for taxis, ride apps and airport transfers in the US, Canada and the UK. It works out what a licensed taxi meter should charge from each city's official tariff (24 cities), what Uber and Lyft typically charge in New York from the city's own trip records (21.6 million trips), the cheapest time to ride, airport pickup rules, drop-off charges and flat fares (36 airports), whether a fare paid looks fair, with the next steps and a ready message if not, and whether a New York driver's licence is active. Every answer has a say field with a ready-made summary. Nothing about users is stored.",
  "contact": {
   "name": "Fair Fare",
   "email": "fairfare@goodturnstudio.com",
   "url": "https://fairfare.pages.dev"
  },
  "license": {
   "name": "Free to use; see terms",
   "url": "https://fairfare.pages.dev/terms"
  }
 },
 "servers": [
  {
   "url": "https://fairfare.pages.dev/v1"
  }
 ],
 "paths": {
  "/estimate": {
   "get": {
    "operationId": "estimateFare",
    "summary": "What a trip should cost by taxi, Uber or Lyft",
    "description": "Distance and time by road between two places, the licensed taxi meter fare with the extras that apply at that hour, any airport flat fare, typical Uber and Lyft prices in New York, airport pickup rules, a pre-booked transfer option for airport trips, and links that open Uber, Lyft or public transport directions with the trip filled in.",
    "parameters": [
     {
      "name": "from",
      "in": "query",
      "required": true,
      "description": "Where the trip starts: an address, landmark, postcode, airport code (JFK, LHR) or lat,lon.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "to",
      "in": "query",
      "required": true,
      "description": "Where the trip ends, in the same forms as from.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "when",
      "in": "query",
      "required": false,
      "description": "When the trip starts, in local time: now (the default), a time like 18:30 or 6pm, or a date and time like 2026-10-09T18:30.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "city",
      "in": "query",
      "required": false,
      "description": "Optional tariff city id from list_cities, when the place names are ambiguous.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Estimate with a say line"
     }
    }
   }
  },
  "/check_fare": {
   "get": {
    "operationId": "checkFare",
    "summary": "Was I overcharged? Check a fare that was paid",
    "description": "Compares what was paid with the official meter tariff, the airport flat fare or New York's typical Uber and Lyft prices for the same trip and hour, gives a verdict (fair, high or overcharged), the next steps for that company or city regulator, and a short message to send asking for a refund.",
    "parameters": [
     {
      "name": "paid",
      "in": "query",
      "required": true,
      "description": "What was paid, without the tip, for example 48.50.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "kind",
      "in": "query",
      "required": false,
      "description": "taxi, uber, lyft, bolt or minicab. Defaults to taxi.",
      "schema": {
       "type": "string",
       "enum": [
        "taxi",
        "uber",
        "lyft",
        "bolt",
        "minicab",
        "private_hire"
       ]
      }
     },
     {
      "name": "from",
      "in": "query",
      "required": false,
      "description": "Where the trip started.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "to",
      "in": "query",
      "required": false,
      "description": "Where it ended.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "city",
      "in": "query",
      "required": false,
      "description": "Tariff city id, when giving miles instead of from and to.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "miles",
      "in": "query",
      "required": false,
      "description": "Trip length in miles, instead of from and to.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "minutes",
      "in": "query",
      "required": false,
      "description": "Trip time in minutes, if known.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "when",
      "in": "query",
      "required": false,
      "description": "When the trip starts, in local time: now (the default), a time like 18:30 or 6pm, or a date and time like 2026-10-09T18:30.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Verdict with next steps"
     }
    }
   }
  },
  "/best_time": {
   "get": {
    "operationId": "bestTimeToRide",
    "summary": "Cheapest time of day to take a ride",
    "description": "For New York, typical Uber and Lyft prices for a trip of a given length at every hour of the week, from the city's trip records, with the cheapest and most expensive hours today and whether waiting saves money. For other cities, how the taxi meter rates change by time of day.",
    "parameters": [
     {
      "name": "city",
      "in": "query",
      "required": false,
      "description": "Tariff city id, for example nyc, london or chicago. Defaults to nyc.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "miles",
      "in": "query",
      "required": false,
      "description": "Trip length in miles (New York only). Defaults to 3.",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "when",
      "in": "query",
      "required": false,
      "description": "When the trip starts, in local time: now (the default), a time like 18:30 or 6pm, or a date and time like 2026-10-09T18:30.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Hourly prices or tariff bands"
     }
    }
   }
  },
  "/airport": {
   "get": {
    "operationId": "getAirport",
    "summary": "Getting a ride at an airport",
    "description": "Where Uber and Lyft pick up, how the taxi rank works, flat taxi fares, drop-off and pickup charges for cars, meet and greet rules, public transport into the city with prices, and tips, from each airport's own pages.",
    "parameters": [
     {
      "name": "code",
      "in": "query",
      "required": true,
      "description": "Airport code or name, for example JFK, LAX, LHR or Heathrow.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Airport ground transport facts"
     }
    }
   }
  },
  "/tariff": {
   "get": {
    "operationId": "getTaxiTariff",
    "summary": "A city's official taxi meter tariff",
    "description": "The starting charge, the rate per mile or kilometre, the waiting rate, time-of-day tariffs, extras and surcharges, flat fares, tipping custom and the official source.",
    "parameters": [
     {
      "name": "city",
      "in": "query",
      "required": true,
      "description": "Tariff city id from list_cities, for example nyc, chicago, london or birmingham.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Tariff"
     }
    }
   }
  },
  "/licence": {
   "get": {
    "operationId": "checkDriverLicence",
    "summary": "Check a New York taxi or ride-app driver's licence",
    "description": "Whether a TLC licence number is active on New York City's daily open data for for-hire (Uber, Lyft, car service) and taxi drivers, its expiry date, and, if a name is given, whether it matches (the name on the licence is never returned). Other cities get the official way to check.",
    "parameters": [
     {
      "name": "number",
      "in": "query",
      "required": false,
      "description": "The TLC licence number shown in the app or on the partition card.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "name",
      "in": "query",
      "required": false,
      "description": "Optional name the driver gave, to check it matches.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "city",
      "in": "query",
      "required": false,
      "description": "nyc (live check) or another city id for guidance. Defaults to nyc.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Licence status"
     }
    }
   }
  },
  "/cities": {
   "get": {
    "operationId": "listCities",
    "summary": "Cities and airports covered",
    "description": "Every city whose official taxi tariff is on file and every airport with ground transport facts.",
    "responses": {
     "200": {
      "description": "Lists"
     }
    }
   }
  },
  "/fleet_check": {
   "get": {
    "operationId": "checkFleetFile",
    "summary": "Check a cab firm's fleet.json",
    "description": "Reads a taxi or minicab firm's fleet.json (the open format at fairfare.pages.dev/fleet that lets assistants find and book local firms directly) and lists anything to fix.",
    "parameters": [
     {
      "name": "url",
      "in": "query",
      "required": true,
      "description": "The https address of the fleet.json file.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Validation result"
     }
    }
   }
  }
 }
}