Documentation

Introduction

This documentation outlines key observations, known limitations, and conventions related to the GeoNames data dumps and ontologies used, as well as the transformation to RDF and the SPARQL editor.

Known Limitations and Approaches

1. Use of dcterms:modified vs. Absence of dcterms:created

Original GeoNames Data Issue

The GeoNames CSV dumps provide only the last modification date for each feature. This is represented as dcterms:modified in the RDF transformation. However, no corresponding dcterms:created property is present in the source data. This means the creation date of a given feature cannot be derived from the GeoNames dataset.

Alignment Approach

The modification date provided in the CSV (modification date column) is mapped directly to dcterms:modified.
Since dcterms:created is entirely absent from the dataset, no attempt is made to artificially populate it.

2. Namespace Prefix "gn" Variations

Original GeoNames Data Issue

The GeoNames ontology uses the namespace http://www.geonames.org/ontology#. However, in practice both the official files and third-party ones sometimes mix http and https variants of this prefix. These inconsistencies lead to subtle but significant issues:

• Queries using the https:// prefix may not match data stored with an http:// prefix, and vice versa.

Alignment Approach

To avoid mismatches, the officially correct prefix was standardized:
PREFIX gn: <http://www.geonames.org/ontology#>

All pipeline outputs use the http:// form consistently.
A modified version of the GeoNames ontology (ontology_v3.3_modified.rdf), which uses http:// like some of its previous versions, is used to ensure consistent IRI usage across the dataset.

3. Alternate Names and Language Tag Inconsistencies

Original GeoNames Data Issue

The GeoNames CSV dumps contain many alternate names without language codes. These untagged names appear in the alternateNames.txt file with empty language code fields. The language tag formats varies across the available datasets, leading to inconsistencies in how alternate names are represented.

Filtering Approach

To ensure consistency, strict filtering rules were applied in the RDF transformation:

• Alternate names with explicit language codes (e.g., de, en, fr) are included.
• Alternate names with no language codes are included.
• Entries marked as links or postal codes are treated separately and not mixed into alternate names.

4. Handling Population Values

Original GeoNames Data Issue

The GeoNames CSV dumps contain population figures for many features. However, population values of 0 almost always indicate that the actual population is unknown rather than truly zero. Keeping these values in RDF output would misrepresent data, especially in queries filtering for low or zero populations.

Alignment Approach

• Zero‑valued population entries were excluded during transformation.
• Only population values greater than zero are represented as gn:population triples.

5. Postal Codes and Integration Challenges

Original GeoNames Data Issue

GeoNames distributes postal code information separately in its ZIP export files and also encodes some postal codes within alternateNames.txt using the isolanguage = post marker. However, the official GeoNames RDF dumps (about.rdf files) do not consistently include postal codes. This creates a discrepancy between the CSV/ZIP sources and the RDF representation, making it difficult to fully match localities with their corresponding postal regions.

Integration Approach

To address these gaps, postal codes from the available sources were reconciled:

• Postal codes provided via the ZIP files are considered the main reference for coverage.
• Entries from alternateNames.txt marked with post are extracted and added as gn:postalCode values.

Custom Property Additions

• Wikidata Property Integration

  The GeoNames ontology does not provide certain nationally‑specific identifiers that are crucial for linking with government datasets. In the German context, one important identifier is the Amtlicher Gemeindeschlüssel (official municipality key), which uniquely identifies every German municipality.

  Integration Approach

  Wikidata provides the property wdt:P439 for the Amtlicher Gemeindeschlüssel (official municipality key). GeoNames includes the actual key values in its CSV files.

  During integration, the system reuses wdt:P439 as the property to link GeoNames features with their official keys.
  It:

  • reads key values from GeoNames CSV data.
  • assigns them to German municipalities using Wikidata’s wdt:P439.
  • links each feature URI to its corresponding key.

• Altitude data

  Altitude information in GeoNames is available in the CSV dumps under the elevation and dem columns. The elevation value represents the feature’s altitude in meters when available, while the dem (Digital Elevation Model) provides a model‑based average elevation.

  Integration Approach

  During integration, both columns are read and converted to decimal values. The elevation value is the prefered altitude value, and if it is missing, the dem value is used as a fallback altitude value. The resulting altitude is then expressed using the wgs84_pos:alt property of the WGS84 vocabulary.

  This ensures each geographic feature includes a consistent altitude value derived directly from the most reliable available source.

Feature Comparisons

The following tables show side-by-side comparisons of selected example features across different GeoNames sources: about.rdf files (downloaded from the GeoNames website on October 18, 2025), the corresponding HTML pages, the Geonames RDF dump (dated February 14, 2020), and the generated Turtle file geonames_DE_2025-10-18.ttl. These comparisons make it easier to identify consistent values across sources and highlight where differences occur.

The tables make use of standard RDF prefixes, including:

• gn: (http://www.geonames.org/ontology#)
• dcterms: (http://purl.org/dc/terms/)
• rdfs: (http://www.w3.org/2000/01/rdf-schema#)
• wgs84_pos: (http://www.w3.org/2003/01/geo/wgs84_pos#)
• foaf: (http://xmlns.com/foaf/0.1/)
• cc: (http://creativecommons.org/ns#)
• geo: (http://www.opengis.net/ont/geosparql#)
• wdt: (http://www.wikidata.org/prop/direct/)

The following color coding is used: green = consistent, yellow = minor differences, red = missing or major differences.

Using YASR Plugins

The following guide explains how to use YASR plugins for visualizing SPARQL results, including charts, maps, and graphs.

1. Chart Visualization – Customizing the Legend Label

The Chart.js plugin displays bar charts for numeric SPARQL results. By default, the legend label shown is “Count”. To customize this label:

• Using SPARQL: Add a variable ?legendLabel in your query with your desired legend text.

  
  PREFIX gn: <http://www.geonames.org/ontology#>
  
  SELECT ?label ?value ?legendLabel WHERE {
    ?feature a gn:Feature ;
             gn:name ?label ;
             gn:population ?value .
    BIND("Population in 2025" AS ?legendLabel)
  }
  LIMIT 10
        

Ensure your query returns both a category label and a numeric value for correct chart rendering.

• Label variables: ?label, ?classLabel, ?category, ?bucket, ?name
• Numeric value variables: ?value, ?count, ?total, ?num
• Optional legend label: ?legendLabel

2. Interactive Map Pins and Labels

The Leaflet Map plugin visualizes SPARQL query results as interactive map pins, placing markers using latitude and longitude variables from your query.

Each pin displays a popup label from variables such as ?label or ?name to identify the location. The clickable hyperlink on the pin is derived from the URI of the main entity variable (commonly ?feature) in your SPARQL result, which represents the primary resource shown on the map.

To enable effective map visualization and interactivity, ensure your query:

• Includes latitude and longitude variables for positioning pins.
• Returns a descriptive label variable for popup names.
• Contains a unique URI variable (e.g., ?feature) identifying the main geographic entity, which will be the clickable link for the pins.

• Latitude variables: ?lat, ?latitude, ?latDecimal, ?latDeg
• Longitude variables: ?long, ?lon, ?longitude, ?longDecimal, ?longDeg
• URI variables: ?feature, ?uri, ?url
• Label variables: ?label, ?name, ?s

3. Interactive Graph Visualization

The graph visualization plugin turns SPARQL query results into an interactive network graph, where nodes represent entities and edges represent relationships or properties. This visualization helps users explore complex linked data structures visually.

To generate effective graphs, your SPARQL query should:

• Return triples with variables for subject (?s or ?subject), predicate (?p or ?predicate), and object (?o or ?object).
• Include human-readable labels for nodes (e.g., ?label) to improve clarity.
• Optional: Add variables for predicate labels (?pLabel) to display relational context, and variables for node labels for easier interpretation.
• This query retrieves triples representing an administrative hierarchy by linking features (?s) to their parent features (?o), while fetching human-readable names as labels for both subjects and objects and including predicates with their labels for edge descriptions.

  
  PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> 
  PREFIX gn: <http://www.geonames.org/ontology#> 
          
  SELECT ?s ?sLabel ?p ?pLabel ?o ?oLabel 
  WHERE { 
      ?s gn:parentFeature ?o . 
      ?s gn:name ?sLabel . 
      ?o gn:name ?oLabel . 
      ?s ?p ?o . 
      ?p rdfs:label ?pLabel .
  } 
  LIMIT 10
          

• Subject variables: ?s, ?subject
• Predicate variables: ?p, ?predicate
• Object variables: ?o, ?object
• Subject labels: ?sLabel, ?subjectLabel
• Object labels: ?oLabel, ?objectLabel
• Predicate labels (for edge text): ?pLabel, ?predicateLabel

References

• GeoNames Ontology v3.3
• ontology_v3.3_modified.rdf
• GeoNames Mappings v3.01