Solr Plugin

Travel Time Matrix API can be used on Solr using our plugin. Plugin supports the fastest version of Travel Time Matrix endpoint which uses Protocol Buffers for communication. You can find more details about available versions on our endpoint comparison page.

Authentication

For access to the Protobuf endpoint, please contact support@traveltime.com for credentials. Having a TravelTime Account is not enough, not having correct access will produce an authorization error.

Source

The source code and JAR file of the plugin is available on GitHub.

Supported versions

6.5, 6.6, 7.X, 8.X, 9.X. Plugin is not supported for versions 6.4 or lower.

Installation and configuration

To install the plugin you must place the plugin JAR file in the Solr lib directory.

To use the plugin you must add to your configuration a queryParser with the class com.traveltime.plugin.solr.TravelTimeQParserPlugin or com.traveltime.plugin.solr.TimeFilterQParserPlugin. The TravelTimeQParserPlugin uses the Travel Time Matrix Fast (Proto) endpoint. This is the recommended way to use our plugin due to its very low latency and high location volume per request. The TimeFilterQParserPlugin uses the Travel Time Matrix (Time Filter) endpoint. This is more configurable and supports more countries.

These query parsers have two mandatory string configuration options:

app_id: this is your API app id.
api_key: this is your API key that corresponds to the app id.

Both query parsers also have an optional boolean filtering_disabled parameter that defaults to false. If set to true the query will not filter out any documents but will enable scoring and using the travel time field.

The TimeFilterQParserPlugin has an optional integer field location_limit which represents the maximum amount of locations that can be sent in a single request. Defaults to 2000, only increase this parameter if you API plan supports larger requests.

<queryParser name="traveltime" class="com.traveltime.plugin.solr.TraveltimeQParserPlugin">
  <str name="app_id">your_app_id_here</str>
  <str name="api_key">your_app_key_here</str>
</queryParser>

To display the travel times returned by the TravelTime API you must configure two more components: a valueSourceParser, one of:

<valueSourceParser name="traveltime" class="com.traveltime.plugin.solr.query.TravelTimeValueSourceParser"/>
  <valueSourceParser name="traveltime" class="com.traveltime.plugin.solr.query.timefilter.TimeFilterValueSourceParser" />

and a cache, one of:

<cache name="traveltime" class="com.traveltime.plugin.solr.cache.ExactRequestCache"/>
  <cache name="traveltime" class="com.traveltime.plugin.solr.cache.ExactTimeFilterRequestCache"/>
  <cache name="traveltime" class="com.traveltime.plugin.solr.cache.FuzzyRequestCache" secondary_size="50000"/>
  <cache name="traveltime" class="com.traveltime.plugin.solr.cache.FuzzyTimeFilterRequestCache" secondary_size="50000"/>

Example time-filter/fast configuration

<config>
  <query>
    <cache name="traveltime" class="com.traveltime.plugin.solr.cache.FuzzyRequestCache" secondary_size="50000"/>
  </query>
  <queryParser name="traveltime" class="com.traveltime.plugin.solr.TravelTimeQParserPlugin">
    <str name="app_id">your_app_id_here</str>
    <str name="api_key">your_api_key_here</str>
  </queryParser>
  <valueSourceParser name="traveltime" class="com.traveltime.plugin.solr.query.TravelTimeValueSourceParser" />
</config>

Example time-filter configuration

<config>
  <query>
    <cache name="traveltime" class="com.traveltime.plugin.solr.cache.ExactTimeFilterRequestCache"/>
  </query>
  <queryParser name="traveltime" class="com.traveltime.plugin.solr.TravelTimeQParserPlugin">
    <str name="app_id">your_app_id_here</str>
    <str name="api_key">your_api_key_here</str>
  </queryParser>
  <valueSourceParser name="traveltime" class="com.traveltime.plugin.solr.query.timefilter.TimeFilterValueSourceParser" />
</config>

Querying data using proto time-filter/fast requests

The query to TravelTime API can only be used as a filter query and can only be used with fields that are indexed as location.

The query accepts the following configuration options:

origin: the point from which travel time will be measured. The accepted formats are: "lat,lon" and geohash
field`: the document field that will be used as the destination in the Traveltime query.
limit: the travel time limit in seconds. Must be non-negative.
mode: Transportation mode used in the search. One of: pt, walking+ferry, cycling+ferry, driving+ferry.
country: Alpha-2 country code that the origin is in. Must be set either in the query or as a default in the config. Information about supported countries on protobuf endpoint.
(optional) requestType: type of request made to the api. Must be one of ONE_TO_MANY, MANY_TO_ONE. Defaults to ONE_TO_MANY.

The configuration options may be passed as local query parameters:

?fq={!traveltime origin=51.53,-0.15 field=coords limit=7200 mode=pt country=uk}

or as raw query parameters prefixed with "traveltime_":

?fq={!traveltime}&traveltime_origin=51.53,-0.15&traveltime_field=coords&traveltime_limit=7200&traveltime_mode=pt&traveltime_country=uk}

If a parameter is specified in both ways, the local parameter takes precedence.

Query example

https://solr.example.com/solr/_default/search?fq={!traveltime origin=51.53,-0.15 field=coords limit=7200 mode=pt country=uk}

Querying data using json time-filter requests

The query accepts the following configuration options:

field: the document field that will be used as the destination in the TravelTime query.
travel_time: the travel time limit in seconds. Must be non-negative.
transportation: a string containing a JSON object describing the transportation mode as defined by the TravelTime API
range (optional): a string containing a JSON object describing the range search as defined by the TravelTime API

For arrival searches:

arrival_time: arrival time in ISO8601
arrival_location: string containing a JSON object with lat and lng keys describing the coordinates of the arrival location

For departure searches:

departure_time: departure time in ISO8601
departure_location: string containing a JSON object with lat and lng keys describing the coordinates of the departure location

An example query using curl:

Query example

curl
  --data-urlencode 'q=*:*'
  --data-urlencode 'traveltime_field=coords'
  --data-urlencode 'traveltime_travel_time=3000'
  --data-urlencode 'traveltime_arrival_location={"lat":51.536067,"lng":-0.153596}'
  --data-urlencode 'traveltime_arrival_time=2022-12-19T15:00:00Z'
  --data-urlencode 'transportation={"type":"public_transport"}'
  --data-urlencode fq="{!traveltime weight=1}"
  $URL

The configuration options may be passed as local query parameters, or as raw query parameters prefixed with traveltime_. If a parameter is specified in both ways, the local parameter takes precedence.

Multiple traveltime queries in the same request

You can issue multiple traveltime queries in the same request (for example to retrieve both driving and public transport travel times). To achieve this a configuration option of prefix is available. This allows you to specify a parameter key prefix different than traveltime_. For example, for plugins configured with the prefix driving_ and walking_ you can specify the following query parameters:

Multiple queries

driving_origin="51.536067,-0.153596"
driving_field=coords
driving_limit=900
driving_mode=driving
driving_country=uk

walking_origin="51.536067,-0.153596"
walking_field=coords
walking_limit=1200
walking_mode=walking
walking_country=uk

Displaying travel times

To display the travel times you must configure the valueSourceParser and cache. When configured, the time can be accessed using the fl parameter: ?fl=time:traveltime(). The valueSourceParser accepts the same parameters as a query, but only in the raw query parameter form. If no travel time is found in the cache it will be returned as -1.

Request caches

Request caches can be used to enable the valueSourceParser and to reduce request latency for some workloads.

The plugin provides two request cache implementations: ExactRequestCache and FuzzyRequestCache.

ExactRequestCache uses all of the traveltime query parameters as a cache key. Therefore, changing any of the parameters will result in a cache miss. This is recommended if the cache is only needed to display the times in search results, or if the query parameters are mostly static.
FuzzyRequestCache uses only the origin and mode fields as cache keys. This cache is useful for workloads where the set of possible origin parameters is limited since it will limit the amount of API calls needed to fetch data from TravelTime. The secondary_size controls the size of each per-origin traveltime cache. It should be set to at least the number of documents returned by each query.