targomo-java

Java Client API for the Targomo web services

API-Key

Get your API key here.

Add the library to your Maven configuration

<dependency>
    <groupId>com.targomo</groupId>
    <artifactId>java-client</artifactId>
    <version>0.35.0</version>
</dependency>

You also need to add a JAX-RS implementation of your choice. For example Jersey:

 <dependency>
     <groupId>org.glassfish.jersey.core</groupId>
     <artifactId>jersey-client</artifactId>
     <version>2.6</version>
 </dependency>

Please make sure your jersey-client version is compatible with your Java version: here

Java 11

If you are using Java 11 or more, you might need to add those dependencies:

<dependency>
    <groupId>org.glassfish.jersey.inject</groupId>
    <artifactId>jersey-hk2</artifactId>
    <version>2.33</version>
</dependency>
<dependency>
    <groupId>com.sun.activation</groupId>
    <artifactId>jakarta.activation</artifactId>
    <version>1.2.1</version>
</dependency>

Note: if you are using jersey-client, jersey-hk2 must have the same version.

Perform Release

To perform a release simply do: mvn clean deploy -DperformRelease=true. There is also manually triggerable jobs to deploy to our nexus and to the maven repo (last is only possibly from master).

Release Notes

0.35.0

Add statisticsMax criterion type
Add parameter useProbabilityBasedWeightedAverage to MultiGraph Aggregations
Add statisticsDistanceAverage criterion type
Add gravitationDistanceAverage criterion type
Support edgeStatisticId in Edge Stats reachability criterion
Add getter for single TravelType from TravelOptions for backwards compatibility
Remove fallbackUrl logic

0.34.0

Add the possibility to set metadata for criterion definition
Fix edge statistic request options serialization
Add BoundingBox request

0.33.0

Add an equals method for RoutingOptions
Add support for multiModal routing
Add multiGraphH3FixedZoomLevel to TravelOptions

0.32.0

Remove use of the temporary parameter "multiple" for poi gravitation
Add allowPrivateAndServiceRoads parameter
Add arrivalOrDepartureDuration parameter
Add option for sourceAddresses and targetAddresses using H3 Addresses

0.31.0

Allow edgeStatisticsServiceUrl and mobilityServiceUrl to be null
Add Multigraph Tilehash Serialization
Update Poi Gravitation Response with multiple sources
Small fix when serializing targetGeohashes to quote the geohash strings
Add parameter learntMaxEdgeWeight to MultiGraph Aggregations
Allow all domains on H3 layer type

0.30.0

Add a general criterion definition interface
Add multiGraphAggregationSourceValuesModifier to TravelOptions
Add statistics request parameter useH3Reachability, remove iFeelLucky
Add sourceValueModifier to Gravitation criterion
Add aggregation type NEAREST_ROUTING_UNION which aggregates in routing
Add useStatisticTargets Statistics Parameter
Add a new type of quality service's location: reference geometry
Replace lombok annotations with Javax validations in Multiple Criteria
Add @Valid annotations in criteria to enable the validation of nested objects

0.29.0

Add H3 MultiGraph buffering parameters
Add new quality criterion: closest POI absolute distance
Add new quality criterion: edge statistics reachability

0.28.0

Remove maxSnapDistance option from quality criterion root level
Add maxSnapDistance option into travelMode object
Include exclusionGeometry in quality criteria

0.27.0

Add EdgeStatisticsReachabilityRequest
Integrate RoutingAggregationType into StatisticsGravitationCriterion
Add h3hexagon to MultiGraph layer types
Include exclusionGeometry in travel options

0.26.0

Include walkSpeed in request (for bike and car mode)

0.25.2

Hotfix for central maven deployment issue

0.25.1

Fix javadoc errors

0.25.0

Add Snapping Related params to CompetingRouting RoutingOptions.
Fix central maven deployment issue

0.24.0

Add includeSnapDistance, useAreaSnapping, and snapRadius to travel options
Add excludeEdgeClassesFromSnapping to travel options
Add multiGraphIgnoreRoutingErrorMessages boolean in StatisticsTravelOptions to be used to ignore errors in MG requests.

0.23.0

Fix the issue on generating the javadoc
Add collectionId and edgeStatisticsId to EdgeStatisticsCriterionDefinition
Remove multiGraphDomainClipGeometry parameter

0.22.0

Refactor EdgeStatisticsRequest, add possibility to request multiple statistics
Adding forceRecalculate and cacheResult to geometry, reachability, PointsOfInterest requests
Add clipGeometry and multiGraphDomainClipGeometry parameters

0.21.0

Adding new Aggregation types mean sum in CompetingRouting
Update versions for java 17

0.20.0

Fix a bug when no aggregation is specified for statistics values/geometry requests
Add Statistics On Enclosing Cell Criterion
Extend Gravitation Criterion interface
Handle forceRecalculate and cacheResult in quality requests
Add headers to ScoreRequest
Add a new TravelType Fly
Add returnOriginId parameter to StatisticTravelOptions

0.19.0

Improve testing for Location Scoring/Rating requests
Add lat/lng fields to TransitStation POJO
Added lightweight RoutingOption POJO and CompetingRoutingOption POJO to library and into StatisticTravelOptions
added @JsonInclude(JsonInclude.Include.NON_NULL) annotations to quality criteria used in LOOP GeoAI
Integrate CompetingRoutingOptions into StatisticsGravitationCriterion
Add countCells to statistics criterion
Add new Polygon Area criterion
Handle quadrantSegments parameter in PolygonRequest
Be able to set aggregation for statistics values/geometry endpoint
Add forceRecalculate/cacheResult params to TravelOptions
Fix statistics chart response parsing for distance routing

0.18.0

Add Location Scoring requests

0.17.0

Add GeoPackage dependency

0.16.0

Fix maxSnapDistance usage in equals and hash methods
Be able to set custom http headers
Update guava and jackson dependencies

0.15.0

Update mobility service requests
Add multiGraphCalculateGravitationPerReferenceId parameter added in the StatisticTravelOptions.
Add UserServiceReferralUrlClientFilter for services using the client

0.14.0

Add multiGraphDomainStatisticCollectionId parameter in the StatisticTravelOptions.
statisticsCollectionId parameter renamed to statisticCollectionId in the StatisticTravelOptions.
Add option to reachability requests to map / filter target id while parsing the response
Update package versions to fix security vulnerabilities

0.13.0

Add statisticsCollectionId parameter in the StatisticTravelOptions
Add chartInterval parameter in the StatisticTravelOptions

0.12.0

Send interService key and request type in poi and statistics requests
add multiGraphAggregationProbabilityDecay to TravelOptions and probabilityDecay to AggregationConfiguration
Add Transit Stops service
Add poi gravitation parameters: gravitationExponent and probabilityDecay

0.11.0

Add mobility service requests

0.10.0

update log4j to 2.17.1
include heatmap calculations for logit and gravitation + include "gravitationCompetingPositiveInfluence" in AggregationInputParameters for heatmap calculations
allow custom headers for TimeRequest

0.9.0

Upgrade log4j-core to 2.15.0

0.8.0

Add maxSnapDistance parameter in the TravelOptions

0.7.0

Add POIs inside geometry requests
Add statistics values geometry request

0.6.0

adding the logit multigraph aggregations "LOGIT" and "LOGIT_OPTIMIZED"

0.5.1

Revert Jackson version due to incompatibility issues.

0.5.0

added the new aggregationtype "GRAVITATION_HUFF_OPTIMIZED"
add routeFromCentroidOption for routing geometries.

0.4.0

Throw ResponseErrorException if the request failed with an error code

0.3.0

Add POI Gravitation endpoint

0.2.0

Update Readme with POI reachability example

0.1.23

Update osgeo repository

0.1.22

added sourceValuesLowerBound and sourceValuesUpperBound to AggregationConfiguration
added multiGraphAggregationSourceValuesLowerBound and multiGraphAggregationSourceValuesUpperBound to TravelOptions
added minResultValueRatio and minResultValue to AggregationConfiguration
added multiGraphAggregationMinResultValueRatio and multiGraphAggregationMinResultValue to TravelOptions
Fix a bug: send headers in reachability requests to core

0.1.21

Update Readme

0.1.20

Add option to set headers for requests

0.1.19

Add edge statistics request

0.1.18

Replaced general-image dependency
Add POI clusterIds field
Add inter service request type query param
Add missing travel modes properties
Remove some of the travel mode defaults
update JUnit version to 4.13.1

0.1.17

Add POI summary request
updated geocoding URL
Added utility classes to decorate jersey client with http headers

0.1.16

Add targetGeohashes parameter
Update POI reachability response object
Integrate source geometries parameter
Integrate turning penalties

0.1.15

Change elevationEnabled default to true
Changed TimeService response format to return both travelTime and length between a source and a target

0.1.14

updated log4j and slf4j versions
updated the PointOfInterestResponse (since the service return changed slightly)

0.1.13

Added consistent hashCode calculation on Geometry class
Added new exception types according to core service responses
Fixes on RequestConfigurator while parsing the input request data
Some adaptations to use the new poi service
Improvements for travel time estimation

0.1.12

Change overpass response/request to take an alias rather than take the PoI type from travel options. Used for batch service requests, other requests will work as before.
Fixed CurlUtil error that occurred when an immutable list of headers was passed to the method

0.1.11

new aggregation type "count" for multigraph
Update to prepare for use of geometries (LineStrings, Polygons and MultiPolygons) as sources.
added polygonOrientationRule parameter to polygon requests
Updated POIRequest Implementation
Updated Jackson version to 2.9.9
Updated the layer type handling - now it is differentiated between layer type and domain type - IMPORTANT: this will only work once a new Targomo core service has been released
moved elements for statistics requests from TravelOptions into StatisticTravelOptions

0.1.10 skipped

0.1.9

Update to RequestConfigurator to correctly parse trafficJunctionPenalty and trafficSignalPenalty
Removed unused travel options parameter
Updated dependencies

0.1.8

Added the multigraph attribute multiGraphLayerCustomGeometryMergeAggregation which allows using custom layer aggregation types for tiled serializations. The possible values are defined on MultiGraphGeometryMergeAggregationType.
New multiGraphReferencedStatisticIds parameter in TravelOptions used in Statistics service
Updated parameters for MultiGraphAggregationType.MATH
Renaming all references of ignoreOutlier to ignoreOutliers to make it consistent with the RequestConfigurationParser of the core service

0.1.7

Added the multigraph aggregation type "NONE" for the cases that the response layers aren't merged into one
Some small aggregation type validations

0.1.6

Added attributes for gravitational multigraph, multigraph aggregation pipeline and multigraph math aggregation

multiGraphAggregationGravitationExponent (exponent to be used on gravitation attraction function)
multiGraphAggregationPostAggregationFactor (multiplier applied over the multigraph aggregation value)
multiGraphAggregationInputParameters (set of aggregation input attributes to be used on aggregation pipeline)
multiGraphPreAggregationPipeline (map containing named aggregations, to be used on multigraph aggregation pipeline. These aggregations should be stored in order of insertion to not affect the pipeline execution)
new aggregation type: MATH. To use this new aggregation, one should also define multiGraphAggregationMathExpression. An example of mathExpression would be ({POI:00} - {POI:10}) * 2 - {POI:20}, where inside {} are defined ids of sources (or pre-aggregation ids). Since all the values should be present when calculating the expression, minSourceCount will by default be equal to the number of parameters in the expression (minSourceCount will be 3 by default in the aforementioned example).

0.1.5.2

made avoidTransitRouteTypes in TravelOptions transient
added maxWalkingTimeFromSource and maxWalkingTimeToTarget to TravelOptions.equals() and TravelOptions.hashCode()

0.1.5.1

fixed traffic penalty comparison in TravelOptions.equals()

0.1.5

added parameter "avoidTransitRouteTypes"
added parameters for multigraph aggregation pipeline
added parameters "trafficJunctionPenalty" and "trafficSignalPenalty"

0.1.4

added completeTimeMatrix service request and response
added lombok library to project
fixed security warnings + updated build script
added disable cache parameter to TravelOptions

0.1.3

included multigraph service requests and constants/enums

0.0.30

polygon request's HTTP method can now be set via constructor arg
statistics request now sets the service url as a url param
added geometry for server side geometry intersection, also in request builder
statistic results got some convenience methods to aggregate over returned values

0.0.29

refactored everything to new targomo namespace

0.0.28

this version adds the possibility to generate statistics for specific statistic ids. this is especially useful if you don't want to/or you already did a travel time analysis and have somehow selected some statistic cell ids client side

0.0.27

adds a small util that rewrites URLs to curl format (post or get)

0.0.26

Geocoding with Authorization against the ESRI service (including access token handling) - batch geocoding with authorization is a lot faster

0.0.24

GeojsonUtils included: they allow displaying your Geojson data in your browser and transforming it between different geo formats
included toCurl() methods for TimeRequests and RouteRequests
included "rushHour" in TravelOptions

0.0.22

Removed depricated maxRoutingLength and maxRoutingTime from TravelOptions

0.0.21

Fixed penalties for uphill and downhill

0.0.20

Implementation to carry out a Geocoding Request (i.e. translate one or more addresses into geo coordinates)

0.0.13

The hard dependency to Jersey was removed. Instead the user now can and has to provide a JAX-WS implementation of choice as runtime dependency.

This has the downside that some implementation specific set-up has to be performed:

Enabling gzip compression is mandatory when running against Targomo servers. A gzip encoder or interceptor has to be registered with the Client in a library specific way.
Client timeouts have to be set using library specific properties.

PolygonService

Create polygon from source point.

TravelOptions options = new TravelOptions();
options.setTravelTimes(Arrays.asList(200, 400, 600, 800));
options.setTravelType(TravelType.TRANSIT);
options.addSource(new DefaultSourceCoordinate("id1", 40.608155, -73.976636));
options.setServiceKey("ENTER YOUR KEY HERE");
options.setServiceUrl("https://api.targomo.com/germany/");

Client client = ClientBuilder.newClient();
client.register(GZipEncoder.class); // when using jersey
// client.register(new GZIPDecodingInterceptor(10_000_000)); // specific to JAX-RS implementation
PolygonResponse polygonResponse = new PolygonRequest(client, options).get();
System.out.println(polygonResponse.getRequestTimeMillis() + " " + polygonResponse.getCode());
System.out.println(polygonResponse.getResult());

TimeService

Return travel times from each source to each target point.

TravelOptions options = new TravelOptions();
options.setMaxEdgeWeight(900);
options.setEdgeWeightType(EdgeWeightType.TIME);
options.addSource(source);
options.setTargets(targets);
options.setTravelType(TravelType.CAR);
options.setServiceKey("ENTER YOUR KEY HERE");
options.setServiceUrl("https://api.targomo.com/germany/");

Client client = ClientBuilder.newClient();
client.register(GZipEncoder.class); // when using jersey
// client.register(new GZIPDecodingInterceptor(10_000_000)); // specific to JAX-RS implementation
TimeResponse timeResponse = new TimeRequest(client, options).get();
// so the api returns all combinations of source and target with the corresponding travel time, or -1 if not reachable
Map</*Source*/Coordinate, Map</*Target*/Coordinate, Integer>> travelTimes = timeResponse.getTravelTimes();

ReachabilityService

Return total travel time for each source point to all targets.

TravelOptions options = new TravelOptions();
options.setMaxEdgeWeight(900);
options.setEdgeWeightType(EdgeWeightType.TIME);
options.addSource(source);
options.setTargets(targets);
options.setTravelType(TravelType.CAR);
options.setServiceKey("ENTER YOUR KEY HERE");
options.setServiceUrl("https://api.targomo.com/germany/");

Client client = ClientBuilder.newClient();
client.register(GZipEncoder.class); // when using jersey
// client.register(new GZIPDecodingInterceptor(10_000_000)); // specific to JAX-RS implementation
ReachabilityResponse reachabilityResponse = new ReachabilityRequest(client, options).get();
// source ID, total travel time
Map<String, Integer> travelTimes = reachabilityResponse.getTravelTimes();

This service can be used with precached targets (by using statisticGroupId). If these targets are shared among multiple statistics it may be necessary to filter the targets and map their ids. To improve performance this can be done while parsing the response by passing a mapper/filter function. This function can map the target id to a different value or filter targets out by returning null.

// map target id to statistics id and filter out negative statistics ids
Function<String, String> mapperFilter = (String targetId) -> {
    int statisticsId = targetIdToStatisticsId.get(targetId);
    return statisticsId >= 0 ? String.valueOf(statisticsId) : null;
};
ReachabilityResponse reachabilityResponse = new ReachabilityRequest(client, options).get(mapperFilter);

RouteService

Return possible route from each source point to each target.

TravelOptions options = new TravelOptions();
options.setMaxEdgeWeight(900);
options.setEdgeWeightType(EdgeWeightType.TIME);
options.addSource(source);
options.setTargets(targets);
options.setTravelType(TravelType.BIKE);
options.setElevationEnabled(true);
options.setServiceKey("ENTER YOUR KEY HERE");
options.setServiceUrl("https://api.targomo.com/germany/");

Client client = ClientBuilder.newClient();
client.register(GZipEncoder.class); // when using jersey
// client.register(new GZIPDecodingInterceptor(10_000_000)); // specific to JAX-RS implementation
RouteResponse routeResponse = new RouteRequest(client, options).get();
JSONArray routes = routeResponse.getRoutes();

GeocodingService

Return possible geocode(s) for each given address.

Client client = ClientBuilder.newClient();
GeocodingRequest geocodingRequest = new GeocodingRequest(client);

//Request geocoding for single address
GeocodingResponse response = geocodingRequest.get( "Lehrter Str. 56, Berlin" );
DefaultTargetCoordinate geocode = response.getRepresentativeGeocodeOfRequest();

//Request geocoding for many addresses
GeocodingResponse[] manyGeocodes = geocodingRequest.getBatchParallel( 20, 10, 
        "Ohlauer Str. 38, 10999 Berlin",
        "Thiemannstr 1, Tor 4, 2.Hinterhof, 12059 Berlin",
        "Telegrafenweg 21, 13599 Berlin",
        "Wilhelm-Kabus-Straße 40, Berlin");
DefaultTargetCoordinate[] geocodes = Arrays.stream(manyGeocodes)
                .map(GeocodingResponse::getRepresentativeGeocodeOfRequest).toArray(DefaultTargetCoordinate[]::new);

Poi Reachability service

Return reachable POIs from a list of sources

TravelOptions options = new TravelOptions();
options.setMaxEdgeWeight(900);
options.setEdgeWeightType(EdgeWeightType.TIME);
options.addSource(new DefaultSourceCoordinate("id1", 40.608155, -73.976636));
options.setOsmTypes(Collections.singleton(new PoiType("amenity", "restaurant")));
options.setTravelType(TravelType.CAR);
options.setServiceKey("ENTER YOUR KEY HERE");
options.setServiceUrl("https://api.targomo.com/westcentraleurope/");

Client client = ClientBuilder.newClient();
client.register(GZipEncoder.class); // when using jersey
// client.register(new GZIPDecodingInterceptor(10_000_000)); // specific to JAX-RS implementation

PointOfInterestRequest request = new PointOfInterestRequest(client, options);
PointOfInterestResponse poiResponse = request.get();
// so the api returns all restaurant POIs reachable within 15 min by car.

Find a non-exhaustive list of possible OSM types on the OpenStreetMap wiki

Helper to display geojson

You can also display geojson data directly in your browser with the following routine:

TravelOptions options = new TravelOptions();
options.setPathSerializer(PathSerializerType.GEO_JSON_PATH_SERIALIZER);
//set other options

Client client = ClientBuilder.newClient();
client.register(new GZIPDecodingInterceptor(10_000_000)); // specific to JAX-RS implementation
// client.register(GZipEncoder.class); // when using jersey
RouteResponse routeResponse = new RouteRequest(client, options).get();

CoordinateReferenceSystem sourceCRS = CRS.decode("EPSG:3857");
CoordinateReferenceSystem targetCRS = CRS.decode("EPSG:4326");
this.transform = CRS.findMathTransform(sourceCRS, targetCRS);
String geometryGeojson = routeResponse.getRoutes().getString(0); //only first one is extracted for the tour to the first target
FeatureCollection featureCollection = (FeatureCollection) GeoJSONFactory.create(geometryGeojson);
List<Feature> transformedResponse = GeojsonUtil.transformGeometry(this.transform, featureCollection.getFeatures());
Map<String,FeatureCollection> nameToFeatureCollectionMap = Maps.maps( "testViewer.geojson",
        new FeatureCollection(transformedResponse.toArray(new Feature[transformedResponse.size()])) );
GeojsonUtil.openGeoJsonInBrowserWithGeojsonIO(fileMap);  //Display the route in the browser
//alternative method: GeojsonUtil.openGeoJsonInBrowserWithGitHubGist(fileMap);

targomo/targomo-java