Unlocking UK Taxi Bookings with Taxicode API

In the bustling world of digital services, providing convenient and efficient transport solutions is paramount. For businesses looking to integrate a robust taxi booking system, the Taxicode API offers a powerful and flexible solution. This comprehensive interface allows developers to seamlessly connect their applications with a vast network of taxi providers across the UK, enabling users to request quotes, compare options, and book journeys with unprecedented ease. Whether you're building a travel application, a corporate booking tool, or a local service directory, understanding the intricacies of the Taxicode API is your first step towards offering a superior transport experience.

At its core, the Taxicode API functions as a bridge between your platform and a multitude of taxi companies. When your application sends a request for a journey, the API processes this information and returns two crucial objects: a Journey object and a Quotes object. The Journey object acts as a confirmation, echoing the details of the requested trip, ensuring accuracy and clarity. The Quotes object, however, is where the true power lies, containing a wealth of information about available taxi services, their pricing, and various customisation options. These quotes are conveniently keyed with unique quote IDs, which are vital for the subsequent booking process and are retained on Taxicode's servers for a period of 24 to 48 hours before being automatically deleted. This temporary storage ensures that you have a window to confirm and book the chosen journey.

Deciphering the API Response

Understanding the response from the Taxicode API is critical for building a reliable integration. Each response includes a status indicator, informing you of the outcome of your request:

• OK: This status signifies that everything is in order, and valid quotes have been successfully returned.
• WARNING: A WARNING status indicates that while quotes were returned, there might be an issue preventing them from being booked. This often comes with a detailed warning message, guiding you on the specific issue.
• ERROR: An ERROR status means that a problem occurred, and no quotes could be returned. An accompanying error message will provide details about what went wrong.

Beyond the status, the response also provides key identifiers and pathways for booking. The journey_id is a unique identifier for the requested journey, which is stored for up to a month after a booking is made. This can be particularly useful for retrieving journey details or refilling user forms if your application doesn't retain this information. Crucially, if you opt not to handle payments directly, the API provides a payment_url. This URL is your gateway to completing the booking process, and it needs to be dynamically constructed by appending the chosen QUOTE_ID along with other essential variables.

Customising the Payment Experience with URL Variables

The payment_url is highly configurable, allowing you to tailor the booking experience to your users. Several optional and required variables can be appended to this URL:

• callback (Optional String): This is a crucial URL that Taxicode will redirect your customer back to after they complete the payment process. Taxicode will append either ?edit=JOURNEY_ID or ?success=BOOKING_REF to this URL, indicating whether the customer needs to edit their booking or if it was successful. It's important to note that a customer might abandon the process at this stage, so a return to your domain isn't always guaranteed.
• key (Required String): Your public API key. This is essential for identifying your application and authenticating your requests.
• v (Optional Integer): This variable allows you to specify the ID of a particular vehicle that the user wishes to book. The ID corresponds to the array index of the vehicles returned within the booking/quote function.
• mag (Optional 1 or 0): If the selected quote includes an optional meet and greet service, setting mag=1 indicates that the customer has opted for this service. If not provided or set to 0, meet and greet will not be included.
• onbehalf (Optional 1 or 0): Setting onbehalf=1 automatically selects the 'booking on behalf of someone else' option on the payment page. This is particularly useful for applications catering to travel agents or corporate clients who are booking for their customers or employees.
• currency (Optional String): This allows you to display an approximate price in a currency other than GBP. You provide the 3-letter ISO 4217 currency code. It's vital to remember that while the display currency changes, customers will always be charged in GBP. Taxicode supports a wide array of currencies, as detailed in the table below. Should you require additional currencies, direct contact with Taxicode is advised.
• test (Optional 1 or 0): This variable is invaluable for developers. Setting test=1 marks the booking as a test booking. This means the booking will not be dispatched to an actual taxi company but will instead be processed by a special testing company. Payments for test bookings utilise SagePay's testing servers, allowing you to use any test card details for simulation. Setting test=0 or omitting the variable will process the booking as a live transaction.

Supported Currencies for Display

Anatomy of the Journey Object

The Journey object confirms the details of the taxi trip you've requested. It's structured to provide a clear overview of the route and passenger requirements:

• pickup (Location Object): Details the starting point of the journey.
• vias (Location Object or false): If there are any intermediate stops, they are listed here. If no via points, this will be false.
• destination (Location Object): Specifies the final drop-off point.

Each Location Object contains:

• position (Array): An array containing the latitude and longitude coordinates.
• postcode (String): Any matched postcode for the location.
• string (String): A human-readable string representation of the location.

Further journey details include:

• date (UNIX Timestamp): The exact date and time of the outbound journey.
• return (UNIX Timestamp or false): If it's a return journey, this specifies the date and time of the return leg. Otherwise, it's false.
• people (Integer 1-30): The total number of passengers for the journey.
• distance (Integer): The estimated distance of the journey in miles.
• duration (Integer): The estimated duration of the journey in seconds.
• duration_text (String): A more user-friendly, human-readable version of the journey duration.
• quote_type (String): Indicates whether the quote is based on hourly rates or mileage.

Exploring the Quotes Object – Your Gateway to Choices

The Quotes object is where you'll find all the available taxi options. If no quotes are found, it will simply return false. Otherwise, it's an object where each key is a unique Quote ID, and its value is a Quote Object containing comprehensive details about a specific taxi service and its offering:

• active (Boolean): Indicates whether the company is currently an active result. Companies might be inactive if they require more booking notice than the current request allows.
• notification (Integer): The minimum number of hours' notice this particular company requires for a booking.
• cutoff (String): The exact date and time (in YYYY-MM-DD HH:MM:SS format) until which the quote remains valid and can be booked. This takes into account the company's notice period.
• class (String): The general class of vehicles offered by the company, such as standard, executive, or minibuses.
• highlight (String): If the company or quote stands out (e.g., 'best price', 'most reliable'), this field will specify that distinction.
• company_name (String): The name of the taxi company.
• company_id (Integer): The internal ID of the company within the Taxicode system.
• instance_id (Integer): If a company operates multiple branches, this identifies the specific instance or branch that provided the quote.
• company_location (String): The geographical base of the company or the branch that generated the quote.
• company_phone (Float or false): The contact phone number for the company. Will be false if no number is listed.
• price (Float): The standard price of the journey in GBP.
• payment_options (Array): A list of accepted payment methods, such as CARD, BALANCE (for logged-in users with account balance), or CASH (also for logged-in users, provided no affiliate uplift is applied).
• performance (Float): A score out of 10 representing the company's performance. Companies with a score below 8 are generally not displayed unless no other options are available, ensuring a high standard of service.
• meetandgreet (Meet And Greet Object or false): If a meet and greet service is available, this object provides details:
  • location (String): The name of the location where the meet and greet will occur (e.g., 'Arrivals Terminal').
  • price (Float): The additional cost for the meet and greet option.
  • waiting_time (String): The number of minutes of complimentary waiting time included.
  • waiting_time_extra (String): The additional charge for every 15 minutes of waiting beyond the included time.

  If no meet and greet option is available, this will be false.

• rating (Optional Rating Object or false): If ratings are available for the company, this object provides:
  • ratings (Integer): The total number of ratings received.
  • score (Float): The average rating score out of 5.

  If no ratings exist, this will be false.

• vehicles (Array of Vehicle Objects): An array detailing specific vehicle types available for the journey, including:
  • class (String): The vehicle class (e.g., 'standard saloon').
  • count (Integer): The number of vehicles of this type required to meet the passenger count.
  • price (Float): The price for the journey using this specific vehicle type.
  • meetandgreet_price (Float): The price for the journey with meet and greet applied, using this specific vehicle type.
  • name (String): The name of the vehicle model.
  • image (String): A URL to an image of the vehicle.
  • passengers (Integer): The maximum number of passengers the vehicle can accommodate.
  • luggage_big (Integer): The capacity for large luggage items.
  • luggage_small (Integer): The capacity for small luggage items.
• other_rates (Array of Other Rate Objects): If alternative rate types are calculated (e.g., for black cabs), this array provides details, where each object includes:
  • count (Integer): The number of vehicles needed for this rate type.
  • lower_price (Float): The lower estimated price in GBP.
  • upper_price (Optional Float): The upper estimated price in GBP.
  • about (String): Descriptive text about the rate type.
• card (Array of Card Objects): An array listing supported card types for payment and any associated fees, useful for displaying payment options to customers:
  • code (String): The code for the card type.
  • name (String): The name of the card type (e.g., 'Visa', 'Mastercard').
  • uplift (Float): The percentage uplift (fee) that will be charged for using this card type.

Benefits of Integrating the Taxicode API

Integrating the Taxicode API into your platform offers numerous advantages, transforming how your users access and book taxi services:

• Real-time quotes: Provide instant, accurate pricing, enhancing user trust and decision-making.
• Seamless integration: The well-documented API allows for straightforward implementation, reducing development time and effort.
• Customisation options: From payment methods to specific vehicle types and meet and greet services, the API offers extensive flexibility to tailor the booking experience.
• Comprehensive data: Access detailed information about companies, vehicles, ratings, and pricing, empowering users with all the necessary details to make informed choices.
• Testing environment: The dedicated test mode allows developers to thoroughly test their integration without incurring actual charges or dispatching live bookings, ensuring a robust and error-free deployment.
• Enhanced User Experience: By offering a wide array of options and transparent pricing, you can significantly improve customer satisfaction and loyalty.

Frequently Asked Questions (FAQs)

What is a Quote ID and how long is it valid?

A Quote ID is a unique identifier for a specific taxi quote returned by the Taxicode API. These IDs are stored on Taxicode's servers for 24 to 48 hours. You must use this Quote ID if you wish to proceed with booking the quoted journey within this validity period.

Can I handle payments myself?

Yes, you have the option to handle payments directly within your application. However, if you prefer not to, the Taxicode API provides a payment_url which you can redirect your users to. This URL securely handles the payment process via Taxicode's integrated payment gateway.

What currencies are supported for display, and will my customers be charged in that currency?

The Taxicode API supports a wide range of currencies for display purposes, allowing you to show approximate prices in the user's local currency. However, it's crucial to note that all actual charges to the customer will be processed in GBP (Pound Sterling), regardless of the displayed currency.

How do I test my API integration without making live bookings?

The Taxicode API offers a dedicated test mode. By setting the test=1 parameter in the payment_url, your booking will be processed as a test. This means it won't be sent to an actual taxi company, and payments will be handled by SagePay's testing servers, allowing you to use test card details for simulation.

What happens if no quotes are returned for a journey?

If no quotes are found for a requested journey, the API response will return false for the quotes object and a status of ERROR. An accompanying error message will usually provide details on why no quotes were available, such as no companies operating in the area or insufficient notice period.

What does the 'performance' score signify?

The performance score is a rating out of 10 that indicates the reliability and service quality of a taxi company. Companies with a score below 8 are typically not displayed in the quotes unless there are no other companies available, ensuring that users are offered high-quality service providers.

How far in advance can a booking be made?

The ability to book in advance depends on the individual taxi company's notice period. The notification field within a Quote Object specifies the minimum hours of notice a company needs. The cutoff field indicates the exact date and time until which a specific quote can be booked, taking this notice period into account.

What is 'Meet and Greet' and how does it work?

Meet and Greet is an optional service offered by some taxi companies, typically for airport pickups. It means the driver will meet the passenger inside the terminal (or a designated meeting point) with a name board. The meetandgreet object in the API response provides details such as the meeting location, additional cost, and included waiting time.

Conclusion

The Taxicode API provides a robust and flexible framework for integrating taxi booking capabilities into any application. Its comprehensive data structures, customisation options, and dedicated testing environment** empower developers to create highly functional and user-friendly transport solutions. By leveraging the detailed information provided in the Journey and Quotes objects, and mastering the various parameters of the payment URL, businesses can offer their customers a truly seamless and efficient way to book taxis across the UK. Embrace the power of the Taxicode API to enhance your service offerings and drive customer satisfaction.

If you want to read more articles similar to Unlocking UK Taxi Bookings with Taxicode API, you can visit the Taxis category.