Skip to content

data

Jump to bottom
eve edited this page May 13, 2021 · 18 revisions

Data Formats

This page is a full description of all dataformats that are supported by k3b-geoHelper.

Data Formats Table of content

Introduction

k3b-geoHelper's main purpose is to handle points and regions of the world that can be shown in a map.

A region of the world usually has a

  • geographic coordinate that defines the center of the region as latitude-north and longitude-east.
  • zoomlevel that defines how big the visible part of the world is. With zoomlevel 1 you can see all continents. With zoomlevel 6 you see one country. With zoomlevel 13 you will see streets.
  • optionally a name that can become a title of a bookmark.

A point-of-interest or poi-marker usually has a

  • geographic coordinate in the map as latitude-north and longitude-east
  • optionally a description some plain or html text describing the point-of-interest.
  • optionally a name of the point-of-interest.
  • optionally a link with a url pointing to additional informations.
  • optionally a symbol with a png or jpg icon url belonging to the point-of-interest.

There are several possible dataformats that k3b-geoHelper can handle:

Here is a short introduction of the supported formats. You can find a more detailed description in the fields section.

Geo uri with k3b-s extensions

A geo uri describes a visible region to display or a geografic point of interest

In general a geo uri looks like this

  • geo:lat,lon?q=(name)&z=zoomLevel&z2=ZoomMax&link=link&s=symbol&d=description&id=id&t=time
  • geo:0,0?q=lat,lon(name)&z=zoomLevel&z2=zoomMax&link=link&s=symbol&d=description&id=id&t=time

Example:

  • geo:0,0?q=52.366667,9.716667(Hannover)

The same way as a webbrowser can interprete a url like http://github.com/ android apps and the k3b-geoHelper library can interprete geo:0,0?q=52.366667,9.716667(Hannover) .

Since k3b-geoHelper needs more than the current geo uri standard defines there are some k3b-geoHelper-specific additions to the format. For a complete list see fields section.

Note: uri field content

  • it can be url-encoded, but it is not neccessary.
  • it must be url-encoded if the field contain url-special-chars ? or &

In other words

  • geo:...&d=hello+world&...and
  • geo:...&d=hello%20world&.. are valid geo uris while
  • geo:...&d=hello world&...is not a valid uri but k3b-geoHelper understands it.

Note: Currently GoogleMaps for android supports "geo:0,0?q=52.366667,9.716667(Hannover)" but not "geo:52.366667,9.716667?q=(Hannover)"

See also: gero-uri junit-tests

gpx-1.0 and gpx-1.1 xml file format

gpx-1.0 and gpx-1.1 is a standard xml fileformat to describe one ore more geografic points of interest.

In general gpx xml looks like this:

  • <gpx version="1.0" ...><wpt lat="lat" lon="lon"><name>name</name>....</wpt></gpx>
  • <gpx version="1.1" ...><trk><trkseg><trkpt lat="lat" lon="lon"><name>name</name>....

k3b-geoHelper will extract a poi-marker for every gpx wpt or trkpt element. For a complete list see fields section.

See also gpx junit-regression-testdata

  • /k3b-geoHelper/src/test/resources/de/k3b/geo/io/regressionTests/gpx10.gpx and
  • /k3b-geoHelper/src/test/resources/de/k3b/geo/io/regressionTests/gpx11.gpx

kml-2.2 xml file format

kml is the xml fileformat that is used by google.

In general kml looks like this

  • <kml>...<Placemark>...<coordinates>lon,lat</coordinates>...<name>name</name>....</kml>

k3b-geoHelper will extract a poi-marker for every kml Placemark element.

For a complete list see fields section.

See also kml junit-regression-testdata

  • /k3b-geoHelper/src/test/resources/de/k3b/geo/io/regressionTests/kml22.kml.

wikimedia web-api-xml file format

This is the xml fileformat that is used by the web-apis of wikimedia, wikipedia, wikivoyage, ... .

Example: this query asks the german wikivoyage.org for entries around "Las Palmas, Gran Canaria"

In general wikimedia looks like this

<api ...><query><pages>
	<page pageid='7445' title='Las_Palmas' touched='2015-02-10T08:04:45Z' fullurl='https://de.wikivoyage.org/wiki/Las_Palmas'>
		<coordinates><co lat='52' lon='9'/></coordinates>
		<thumbnail source='theIconUrl' width='50' height='38'/>
	</page>
</pages></query></api>

k3b-geoHelper will extract a poi-marker for every page element.

For a complete list see fields section.

See also wikimedia junit-regression-testdata

  • /k3b-geoHelper/src/test/resources/de/k3b/geo/io/regressionTests/wikimedia.poi.

k3b-s internal poi xml format

The k3b-geoHelper internally uses its own poi xml format to define a visible region and to describe poi-marker details.

Most geo uri parameters correspond to a xml-attribute with the same name.

In general poi looks like this

  • <poi ll='lat,lon' n='name' z='zoomLevel' z2='zoomMax' link='link' s='symbol' d='description' id='id' t='time' geoUri='geoUri' />

k3b-geoHelper will create a poi-marker for every poi element. For a complete list see fields section.

See also poi junit-regression-testdata

  • /k3b-geoHelper/src/test/resources/de/k3b/geo/io/regressionTests/poi.xml.

Data Fields

This paragraph lists the fields currently supported by k3b-geoHelper.

It contains an example for each dataformat that supports the current field.

ll=lat,lon : Latitude(north), Longitude(east)

This field is used to define

note: GoogleMaps on android only understands "geo:0,0?q=..."

n=name : name, title or caption of the point

This field is used to define

note: GoogleMaps on android only understands "geo:0,0?q=179.345,-86.7890123(Name of the point)"

d=description : Information about the point.

This field is used to define

z=zoomLevel : how much detail should be shown

Value 0..18 or -1 if there is no value

  • 1=World
  • 3=Continent (ie Africa)
  • 6=Country (ie Germany)
  • 18=MostDetailed.
  • -1=no zoomlevel

This field is used to define

z2=ZoomMax : (not used yet. reserved for zoom intervalls)

link=link : url pointing to additional informations

any kind of url is possible. ie:

  • http: and https: for internet links
  • file: for local files
  • content: android specific content uri (ie for media items)
  • intent: url to android specific activity
  • geo: url to a point in an other map/zoomlevel

This field is used to define

s=symbol : symbol-id or url pointing to a symbol, preview-image, icon

any kind of url is possible.

If the symbol contains a colon ":" it is interpreted as a url. else as an id.

id=id : unique number or value identifying the point.

Note: In the sample files for the automated /k3b-geoHelper/src/test/resources/de/k3b/geo/io/regressionTests/ the id attribute contain the expected parsing result in geo:-uri format.

t=time : that relates to the point

time is in iso date format ISO8601.

example: if the poi represents a foto then the time corresponds to "when the photo was taken".

For a list of different supported time formats see : time-parser junit-tests

geoUri=geoUri : (xml only) contains info in geo-uri format

  • <poi geoUri='geo:0,0?q=179.345,-86.7890123(Name of the point)' />

This way you can use geo uris in xml.

Note: Since "&" has a special meaning in xml it must be escaped using "& amp;"

infer=1 : (xml with geoUri only) try to infer lat,lon and name from description

  • <poi geoUri='geo:?d=Text containing (Name of the point) with a loc 179.345,-86.7890123' />

the uri parser can try to find name and LatLon from other fields this way.

Clone this wiki locally