de.westnordost.osmapi.traces

Class GpsTracesApi

java.lang.Object

de.westnordost.osmapi.traces.GpsTracesApi

public class GpsTracesApi
extends java.lang.Object

Create, get, edit and delete gpx traces

Constructor Summary

Constructors

Constructor and Description
GpsTracesApi(de.westnordost.osmapi.OsmConnection osm)

Method Summary

Modifier and Type	Method and Description
long	create(java.lang.String name, GpsTraceDetails.Visibility visibility, java.lang.String description, java.lang.Iterable<GpsTrackpoint> trackpoints) Upload a new trace with no tags
long	create(java.lang.String name, GpsTraceDetails.Visibility visibility, java.lang.String description, java.util.List<java.lang.String> tags, java.lang.Iterable<GpsTrackpoint> trackpoints) Upload a new trace of trackpoints.
void	delete(long id) Delete one of the user's traces
GpsTraceDetails	get(long id) Get information about a given GPS trace or null if it does not exist.
void	getAll(de.westnordost.osmapi.map.data.BoundingBox bounds, de.westnordost.osmapi.common.Handler<GpsTrackpoint> handler, int page) Get all the trackpoints in the given bounding box.
void	getData(long id, de.westnordost.osmapi.common.Handler<GpsTrackpoint> handler) Get all trackpoints contained in the given trace id.
void	getMine(de.westnordost.osmapi.common.Handler<GpsTraceDetails> handler) Pass all gps traces the current user uploaded to the given handler
void	update(long id, GpsTraceDetails.Visibility visibility, java.lang.String description, java.util.List<java.lang.String> tags) Change the visibility, description and tags of a GPS trace. description and tags may be null if there should be none.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GpsTracesApi

public GpsTracesApi(de.westnordost.osmapi.OsmConnection osm)

Method Detail

create

public long create(java.lang.String name,
                   GpsTraceDetails.Visibility visibility,
                   java.lang.String description,
                   java.util.List<java.lang.String> tags,
                   java.lang.Iterable<GpsTrackpoint> trackpoints)

Upload a new trace of trackpoints.

Parameters:

name - this is usually the "file name" of the GPX trace (when files are involved)

visibility - the visibility the trace should have

description - short description of the trace. May not be null or empty.

tags - keywords with which this trace can be found. May be null.

trackpoints - The GPX track to upload

Returns:

trace id

Throws:

java.lang.IllegalArgumentException - if either name, description or any single tag is longer than 255 characters

de.westnordost.osmapi.common.errors.OsmBadUserInputException - if the trace is invalid

de.westnordost.osmapi.common.errors.OsmAuthorizationException - if this application is not authorized to write traces (Permission.WRITE_GPS_TRACES)

create

public long create(java.lang.String name,
                   GpsTraceDetails.Visibility visibility,
                   java.lang.String description,
                   java.lang.Iterable<GpsTrackpoint> trackpoints)

Upload a new trace with no tags

See Also:

create(String, GpsTraceDetails.Visibility, String, List, Iterable)

update

public void update(long id,
                   GpsTraceDetails.Visibility visibility,
                   java.lang.String description,
                   java.util.List<java.lang.String> tags)

Change the visibility, description and tags of a GPS trace. description and tags may be null if there should be none.

Parameters:

id - id of the trace to update

visibility - desired visibility of the trace

description - desired description of the trace. May be null.

tags - desired tags of the trace. May be null.

Throws:

de.westnordost.osmapi.common.errors.OsmNotFoundException - if the trace with the given id does not exist

de.westnordost.osmapi.common.errors.OsmAuthorizationException - if this application is not authorized to write traces (Permission.WRITE_GPS_TRACES) OR if the trace in question is not the user's own trace

java.lang.IllegalArgumentException - if the length of the description or any one single tag is more than 256 characters

delete

public void delete(long id)

Delete one of the user's traces

Parameters:

id - id of the trace to delete

Throws:

de.westnordost.osmapi.common.errors.OsmAuthorizationException - if this application is not authorized to write traces (Permission.WRITE_GPS_TRACES) OR if the trace in question is not the user's own trace

get

public GpsTraceDetails get(long id)

Get information about a given GPS trace or null if it does not exist.

Parameters:

id - id of the trace to get

Returns:

The information for the trace with the given id.

Throws:

de.westnordost.osmapi.common.errors.OsmAuthorizationException - if this application is not authorized to read the user's traces (Permission.READ_GPS_TRACES) OR if the trace in question is not the user's own trace and at the same time it is not public OR if not logged in at all

getData

public void getData(long id,
                    de.westnordost.osmapi.common.Handler<GpsTrackpoint> handler)

Get all trackpoints contained in the given trace id. Note that the trace is a GPX file, so there is potentially much more information in there than simply the trackpoints. However, this method only parses the trackpoints and ignores everything else.

Parameters:

id - id of the trace to get the data for

handler - Handler to which the trackpoints are fed to

Throws:

de.westnordost.osmapi.common.errors.OsmNotFoundException - if the trace with the given id does not exist

de.westnordost.osmapi.common.errors.OsmAuthorizationException - if this application is not authorized to read the user's traces (Permission.READ_GPS_TRACES) OR if the trace in question is not the user's own trace and at the same time it is not public OR if not logged in at all

getMine

public void getMine(de.westnordost.osmapi.common.Handler<GpsTraceDetails> handler)

Pass all gps traces the current user uploaded to the given handler

Throws:

de.westnordost.osmapi.common.errors.OsmAuthorizationException - if this application is not authorized to read the user's traces (Permission.READ_GPS_TRACES)

getAll

public void getAll(de.westnordost.osmapi.map.data.BoundingBox bounds,
                   de.westnordost.osmapi.common.Handler<GpsTrackpoint> handler,
                   int page)

Get all the trackpoints in the given bounding box. As of April 2016, trackpoints returned by the method will only have a position and (sometimes) a time set.

Parameters:

bounds - the bounding box in which to get the trackpoints

handler - Handler to which the trackpoints are fed to

page - since there are loads and loads of traces, the method will only return a certain number of trackpoints per page (see Capabilities.maxPointsInGpsTracePerPage). You can repeat calling this method, incrementing the page number until you get an empty response

Throws:

de.westnordost.osmapi.common.errors.OsmQueryTooBigException - if the bounds area is too large

java.lang.IllegalArgumentException - if the bounds cross the 180th meridian or page is < 0