Skip to content

data

Jump to bottom
k3b edited this page Mar 17, 2023 · 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 &

Examples that the lib can parse:

  • 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.

gpz or .gpx.zip means gpx in zip file that may also contain the referenced Symbol images. The Zip structure is inspired by the kmz zip format.

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.

.kmz or .kml.zip means kml in zip file that may also contain the referenced Symbol images.

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>

Wikidata is slightly different

Example: this query asks wikidata.org for entries around the greek island of "Rhodos"

The answer looks like this

<api ...><query><pages>
	<page _idx="34777" pageid="34777" ns="0" title="Q31833" ... >
		<entityterms>
			<label>
				<term>Aquarium of Rhodes</term>
			</label>
			<description>
				<term>
				research centre, aquarium and museum in Rhodes, Greece
				</term>
			</description>
		</entityterms>
		<coordinates>
			<co lat="36.4571" lon="28.2207" primary="" globe="earth"/>
		</coordinates>
	</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.

.poz or .poi.zip means poi in zip file that may also contain the referenced Symbol images. The Zip structure is inspired by the kmz zip format.

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 or various http(s)-geo-url formats

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