Comprehensive API Documentation for the Diana API

This document provides all the details necessary for a developer to integrate the Diana API into applications. It includes endpoints for travel connections, address autocomplete, and journey sharing functionality.

PDF available under: Diana_API_Docs.pdf

Table of Contents

1. Overview
2. Endpoint Details
   • Connections
   • Journey
   • Address Autocomplete
   • Reverse Geocoding
   • Quota Check
   • Generate Ticketshop Link
   • Share Journey
   • Retrieve Shared Journey
3. Request Parameters
4. Guide: Using Activity Time Parameters
5. Understanding the Response
   • Connections Response
   • Journey Response
   • Address Autocomplete Response
   • Reverse Geocoding Response
   • Quota Check Response
   • Generate Ticketshop Link Response
   • Share Journey Response
   • Retrieve Shared Journey Response
6. Errors and Codes
7. Example Usage
8. Troubleshooting & Edge Cases

Overview

The Diana API provides:

1. Detailed, real-time travel information to and from specified activities (/connections).
2. Simple A-to-B route planning (/journey).
3. Address autocomplete functionality for location searches (/address-autocomplete).
4. Reverse geocoding capabilities (/reverse-geocode).
5. Customer quota and plan status (/quota).
6. On-demand ticketshop link generation for specific journeys (/generate-ticketshop-link).
7. The ability to create and retrieve shareable journey links (/share/...).

All timestamps sent to or received from the API are in UTC. API usage may be subject to a monthly quota.

Endpoint Details

Connections

HTTP Method: GET

URL: /connections

Authentication:

• OAuth 2.0 with read_diana scope
• Bearer Token must be included in the Authorization header: Bearer [token]

Calculates optimal travel journeys to and from a dynamically defined activity. The activity's details (locations, times, duration) are passed directly as request parameters. Implements fallback logic to find the latest possible return journey if the initially calculated timeline yields no results. All time parameters must be sent in UTC.

Note: The time parameters for this endpoint are highly flexible. See the "Guide: Using Activity Time Parameters" section for a detailed explanation of how they work.

Monthly Quota

Starter-Plan users are limited to a monthly request quota on this endpoint.

• A standard request counts as 1 towards the quota.
• Exceeding this quota will result in an error response (see Errors and Codes).

Pro-Plan users are not affected by a request quota.

Realtime requests are automatically made, when possible, and if the user has a Realtime Addon.

For more information see Diana GreenConnect Info Page

Journey

HTTP Method: GET

URL: /journey

Authentication:

• OAuth 2.0 with read_diana scope
• Bearer Token must be included in the Authorization header: Bearer [token]

Calculates simple A-to-B public transport connections. This endpoint is designed for straightforward routing from a starting point to a destination at a specific time.

Monthly Quota

This endpoint shares the same monthly quota as the /connections endpoint for Starter-Plan users. Each request counts as 1 towards the quota.

Address Autocomplete

HTTP Method: GET

URL: /address-autocomplete

Authentication:

• OAuth 2.0 with read_diana scope
• Bearer Token must be included in the Authorization header: Bearer [token]

Reverse geocoding

HTTP Method: GET

URL: /reverse-geocode

Authentication:

• OAuth 2.0 with read_diana scope
• Bearer Token must be included in the Authorization header: Bearer [token]

Quota Check

HTTP Method: GET

URL: /quota

Authentication:

• OAuth 2.0 with read_diana scope
• Bearer Token must be included in the Authorization header: Bearer [token]

Provides an endpoint for customers to check their current quota usage and active plan details.

Generate Ticketshop Link

HTTP Method: POST

URL: /generate-ticketshop-link

Authentication:

• OAuth 2.0 with read_diana scope
• Bearer Token must be included in the Authorization header: Bearer [token]

Generates a ticketshop deeplink for a single, specific connection on-demand. The client sends the connection_elements array of the desired journey, and the API returns the corresponding ticketshop URL if one can be generated.

Share Journey

HTTP Method: POST

URL: /share

Authentication:

• OAuth 2.0 with read_diana scope
• Bearer Token must be included in the Authorization header: Bearer [token]

Creates a unique, shareable link for a specified journey by saving its data. Returns a unique hash ID.

Retrieve Shared Journey

HTTP Method: GET

URL: /share/<hash_key>

Authentication:

• OAuth 2.0 with read_diana scope
• Bearer Token must be included in the Authorization header: Bearer [token]

Retrieves the data for a previously shared journey using its unique hash key.

Request Parameters

Connections Parameters

The activity is defined directly via query parameters.

Journey Parameters

Address Autocomplete Parameters

Reverse Geocoding Parameters

Generate Ticketshop Link Parameters (Request Body)

Share Journey Parameters (Request Body)

Retrieve Shared Journey Parameters (URL)

Guide: Using Activity Time Parameters

To help you find the perfect journey, our API asks for four key time parameters for your activity.

Think of these not as exact times, but as the flexible windows you are available. This guide will show you how to set them and how our API uses them to find the best recommended journey for you.

The four parameters are:

• activity_earliest_start_time: The earliest you are willing to arrive at your activity.
• activity_latest_start_time: The latest you must arrive (e.g., when the activity officially begins).
• activity_earliest_end_time: The earliest you are willing to depart from your activity.
• activity_latest_end_time: The latest you are willing to depart.

1. The "To Activity" Journey (Your Arrival Window)

This journey is defined by earliest_start_time and latest_start_time.

• activity_latest_start_time: This is your hard deadline. If your event starts at 10:00, set this to 10:00. The API will not recommend any journey that arrives after this time.
• activity_earliest_start_time: This is your "buffer." If your event is at 10:00, you might be willing to arrive as early as 09:00 to grab a coffee. Setting this to 09:00 gives the API more options.

How We Find Your "Best" Arrival

Our API searches for all connections that arrive within your window. The "best" (recommended) connection is not the one that arrives at the last possible second.

Instead, we find a "sweet spot" that gives you a comfortable buffer without making you wait too long. We generally aim for a time about one-third of the way into your arrival window, but later options are also considered.

Example:

• earliest_start_time: 09:00
• latest_start_time: 10:00
• Your Window: A 60-minute arrival window.
• Our "Sweet Spot" Target: 09:20 (20 minutes after your earliest time)

The API will recommend the journey that arrives closest to 09:20.

Visualization: Your Arrival Window

          [ YOUR ARRIVAL WINDOW ]
|---------------------------------------------|
|                                             |
09:00                                       10:00
(earliest_start_time)                     (latest_start_time)
      |
      |
    09:20
  (Our "Sweet Spot"
  Target for the
  best recommendation)

2. The "From Activity" Journey (Your Departure Window)

This journey is defined by earliest_end_time and latest_end_time and is linked to your arrival.

• activity_earliest_end_time: The earliest you might leave.
• activity_latest_end_time: The absolute latest you're willing to depart.

How We Find Your "Best" Departure (The Smart Part)

This is where our API's logic really helps. The "best" departure time isn't just a random time in your window; it depends on your recommended arrival time and your activity's duration.

Our API automatically calculates your actual finish time from the recommended arrival and finds the best departure to match.

Example:

• Your "To Activity" recommendation has you arriving at 09:20.
• Your activity_duration_minutes is 180 (3 hours).
• Your earliest_end_time is 12:00.

Calculation:

1. Actual Finish Time: 09:20 (Arrival) + 3 hours (Duration) = 12:20
2. Compare to Earliest End: Your actual finish time of 12:20 is after your earliest_end_time of 12:00, so it's valid.
3. Find Departure: The API will now search for the best departure connection starting at or around 12:20.

This creates a seamless itinerary where your departure journey is perfectly timed to your arrival.

Visualization: Your Connected Itinerary

|------------------[ ARRIVAL ]------------------|-----------------|-----------------[ DEPARTURE WINDOW ]-----------------|
09:00             09:20                       10:00               12:00                                                14:00
(Earliest Start)  (Recommended                                (Earliest End)                                        (Latest End)
                   Arrival)
                      |
                      +------------- 3 Hour Activity Duration -------------+
                                                                           |
                                                                         12:20
                                                                       (Calculated
                                                                        Departure Time)

Because your calculated departure of 12:20 is inside your [12:00 - 14:00] window, the API will find the best connection leaving around 12:20.

3. Smart Fallback: What If No Return Journey is Found?

What happens if your activity runs so late that no return journeys are available based on your "actual finish time"?

Our API has a smart fallback plan.

1. Find Last Chance: The API will re-scan your "From Activity" window and find the absolute latest departure connection available before your latest_end_time.
2. Work Backwards: It will then take that journey's departure time (e.g., 16:30) and subtract your activity duration (e.g., 3 hours). This gives a new mandatory arrival time (e.g., 13:30).
3. Re-Filter Arrival: The API will re-filter your "To Activity" connections. It will now only show you arrivals that get you to the activity before 13:30, ensuring you can make that last train home.

This ensures that if a valid round-trip is at all possible within your windows, our API will find it.

Understanding the Response

Connections Response

Root Object

The response is a JSON object containing the following keys:

• activity: An object with activity details.
• connections: An object with to_activity and from_activity journeys.
• live: A boolean indicating if the connection used a realtime data provider.

activity Object

connections Object

Journey Object

Each journey in to_activity, from_activity (from /connections), or connections (from /journey) contains the following fields:

Connection Element

A Connection Element represents a single step (e.g., train, bus, or transfer) in the journey. It contains the following:

Vehicle Type Table

All Vehicle Types are returned as a ID. Each ID corresponds to a specific vehicle type. The following table provides the mapping:

Alert Object

Service alerts provide information about disruptions, delays, or other important notices for a leg. Alerts are based on the GTFS Realtime specification. Not every leg has alerts; they are only present when there is relevant service information.

Example Alert:

{
  "cause": "UNKNOWN_CAUSE",
  "effect": "OTHER_EFFECT",
  "header_text": "",
  "description_text": "Buchung und mehr Infos unter https://blaguss.com/reiseangebot/mit-dem-bus-zum-schnee#c4628"
}

Journey Response

Root Object

The response is a JSON object containing the following keys:

• journey_request: An object echoing the validated request parameters.
• connections: An array of Journey Objects.
• recommended_connection_id: The connection_id of the best-scoring journey.

journey_request Object

This object echoes the parameters sent in the request, with defaults applied. See Journey Parameters for fields.

connections Array

This is an array of Journey Objects. See the Journey Object definition under the "Connections Response" section for the full structure.

Address Autocomplete Response

The response is a GeoJSON FeatureCollection with enhanced properties in a new diana_properties object. If no matches are found for the query, the response will be an empty array. Each feature contains:

Feature Object Structure

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [lon, lat]
  },
  "properties": {
    // Original Photon properties (see below)
  },
  "diana_properties": {
    // Enhanced properties (see below)
  }
}

Properties Object

Enhanced Properties (diana_properties object)

Display Name Logic

• Addresses: [street] [housenumber], [city] (e.g., "Stephansplatz 1, Vienna") Falls back to original name if no street available
• Stations: Appends "(Station)" if name lacks station keywords (e.g., "U-Bahn", "Bahnhof") Format: [name] (Station), [city]

Type Hint IDs (Vehicle Type Table)

Matches the same IDs used in Connections API (see above):

Reverse Geocoding Response

The response is the same as the Address Autocomplete response. Only one feature is returned, representing the reverse geocoded location. See Address Autocomplete Response for details.

Quota Check Response

The response is a JSON object containing the customer's quota and plan status.

Example:

{
  "requests_this_month": 50,
  "monthly_quota": 100,
  "current_plans": {
    "starter_plan": "Starter-Plan: Free access to the Diana API",
    "realtime_at": "Access to realtime data in Austria"
  }
}

Generate Ticketshop Link Response

On success, the response is a JSON object containing the generated deeplink.

Example:

{
  "ticketshop_url": "https://shop.oebbtickets.at/en/ticket?stationOrigName=Wien%20Hbf&..."
}

Share Journey Response

The response is a JSON object containing the unique ID for the created share link.

Example:

{
  "shareId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}

Retrieve Shared Journey Response

The response is a JSON object containing the originally saved journey data. The structure matches the request body of the Share Journey endpoint.

Example:

{
    "origin": "Stephansplatz, Vienna",
    "origin_lat": 48.2084,
    "origin_lon": 16.3731,
    "date": "2024-09-15",
    "dateEnd": null,
    "to_connection_start_time": "2024-09-15T08:30:00Z",
    "to_connection_end_time": "2024-09-15T09:15:00Z",
    "from_connection_start_time": "2024-09-15T17:00:00Z",
    "from_connection_end_time": "2024-09-15T17:45:00Z",
    "shareURLPrefix": "[https://example.com/planner](https://example.com/planner)"
}

Errors and Codes

Errors are generally returned with a relevant HTTP status code (e.g., 400, 401, 404, 429, 500).

Standard Error Response Format

For errors identified by the application (typically 4xx status codes), the response body follows this JSON format:

{
  "error": "[ERROR_MESSAGE]",
  "code": "[ERROR_CODE]"
}

Error Code Table

Example Usage

Connections Example

GET /connections?user_start_location=Karlsplatz, Wien&activity_name=Hiking Rax&activity_start_location=47.715575,15.804045&activity_start_location_type=coordinates&activity_end_location=47.682191,15.644807&activity_end_location_type=coordinates&activity_earliest_start_time=08:00&activity_latest_start_time=10:00&activity_earliest_end_time=16:00&activity_latest_end_time=18:00&activity_duration_minutes=210
Authorization: Bearer [token]

Journey Example

GET /journey?from_location=Stephansplatz, Wien&to_location=Wien Hauptbahnhof&date=2025-11-20&time=14:30:00&is_arrival=false
Authorization: Bearer [token]

Address Autocomplete Example

GET /address-autocomplete?q=Wien%20Step&hint_lat=48.208&hint_lon=16.373
Authorization: Bearer [token]

Generate Ticketshop Link Example

POST /generate-ticketshop-link
Authorization: Bearer [token]
Content-Type: application/json

{
    "connection_elements": [
        {
            "provider": "VAO",
            "from_location": "Wien Karlsplatz (U)",
            "from_location_coordinates": {"lat": 48.2004, "lon": 16.3697},
            "to_location": "Wien Hbf",
            "to_location_coordinates": {"lat": 48.1852, "lon": 16.3757},
            "departure_time": "2024-09-15T08:30:00Z",
            "arrival_time": "2024-09-15T08:35:00Z",
            "duration": 5,
            "vehicle_name": "U1",
            "type": "JNY"
        },
        {
            "provider": "VAO",
            "from_location": "Wien Hbf",
            "from_location_coordinates": {"lat": 48.1852, "lon": 16.3757},
            "to_location": "Payerbach-Reichenau Bahnhof",
            "to_location_coordinates": {"lat": 47.694, "lon": 15.861},
            "departure_time": "2024-09-15T08:55:00Z",
            "arrival_time": "2024-09-15T09:58:00Z",
            "duration": 63,
            "vehicle_name": "RJ 557",
            "type": "JNY"
        }
    ]
}

Share Journey Example

POST /share
Authorization: Bearer [token]
Content-Type: application/json

{
    "origin": "Stephansplatz, Vienna",
    "date": "2024-09-15",
    "to_connection_start_time": "2024-09-15T08:30:00Z",
    "to_connection_end_time": "2024-09-15T09:15:00Z"
}

Retrieve Shared Journey Example

GET /share/a1b2c3d4-e5f6-7890-1234-567890abcdef
Authorization: Bearer [token]

For complete examples, see the Postman collection at Diana API Postman Collection.

Troubleshooting & Edge Cases

1. Invalid Coordinates:

   • Returns 400 error with message: Invalid coordinates format for [location]. Please use lat,lon (Code: 2001, 2005, 2009, 8001, 8005)

2. No Connections Found:

   • Returns 404 error with relevant message (Codes: 2017, 2018, 2019, 2022, 2023, 8011, 8012)
   • Maybe due to:
     • No connections fitting the time windows (EST-LST, EET-LET).
     • Calculated duration preventing a valid return journey even with fallback logic.
     • Check activity times, duration, and date.

3. Authentication Errors:

   • Returns 401 Unauthorized for missing, invalid, or expired authentication tokens.
   • Ensure the Authorization header includes a valid Bearer [token].

4. Monthly Quota Exceeded:

   • Returns 429 Too Many Requests with error code 6001.
   • This applies to free-tier users on the /connections and /journey endpoints.

5. Location Not Found / Geocoding Failed:

   • Returns 400 error if a provided location name cannot be geocoded (Codes: 2002, 2006, 2010, 8002, 8006).
   • Returns 500 error if the geocoding service itself fails (Codes: 2003, 2007, 2011, 8003, 8007).

6. Shared Link Invalid or Expired:

   • Returns 404 error with message: This shared link is invalid or has expired. (Code: 5001)

7. Incomplete Data in Response:

   • Missing optional fields in the response (e.g., vehicle_name) might be returned as null or omitted.
   • Client applications should handle null/missing values gracefully (e.g., display "N/A").

8. Date Handling:

   • If date is not provided for a connection search, the current date (UTC) is used.
   • Date must be in YYYY-MM-DD format.
   • All times sent and received are UTC. Client applications are responsible for converting to/from local timezones for display.