Georeferences File Format

This page documents the file format in which georeeferences are described in order to be mapped on the Waqwaq webservice.

Example

Links are given below to an example of georeferences file and the resulting map showing useplaces of paper documents with the motif "lion" as watermark, according to the website of the project Bernstein: The Memory of Paper.

• Sample georeferences file
• Resulting map

Fundamentals

The Waqwaq GIS file is:

• a text file with file extension .jsonp
• in Unicode UTF-8 character encoding
• with content structured according to JSON format

An empty template ready to be filled in with data is provided here.

JSON (JavaScript Object Notation) is a notation for variables and objects in the JavaScript programming language. JavaScript is natively understood by webbrowsers, making data transfer on the web in JSON format easier than with XML, which is also more verbuous. JSON is described in JSON RFC-4627.

Elements

The file content is structured in the following elements:

• padding - programmatical element
• metadata - description of the file content, author, etc.
• data - the georeferences themselves

Structurally they are arrage in the following manner: padding ( ( metadata ) ( data ) ).

Padding

Padding consists in enclosing the data within brackets prefixed by a name. This is needed so as to make the data readable by JavaScript across the Internet without the need of programming a server (see discussion here). Padding transfers the data in to the function indicated in the padding name located in the Waqwaq GIS webservice. For Waqwaq this is vectorsFeed.

Example: vectorsFeed( /... data .../ ).

Metadata

The metadata provides a succint description of the content displayed on the map, it's author, copyright and similar information. Parts of the descriptors originate in the Dublin Core v2008.01.14 standard.

Don't use double-quotes (") inside the metadata fields - these are reserved to delimit the fields. Instead use simple-quotes (').

You can include HTML notation in the metadata. For example, if you want to give a hyperlink, write <a href='http://www.penguins.mil'>link</a>.

Supplying metadata is optional, but a very good practice so as to provide users with a legend clarifying what the map represents.

header - Description of the dataset content.

1. content - Class of fields describing the file content. This information is used as map legend for display on the map user interface.
   1. contentLanguage - Language in which the content is written. Follows ISO 639-2/B-alpha-3 encoding.
      Ex. : "aar", "arc", "zza" for "Afar", "Official Aramaic", respectively "Zaza".
   2. title - Description that can be placed on a map as its title.
      Ex. : Places of plague occurencies in Europe, 1347-1600
   3. abstract - A more detailed description than given in the title.
      Ex. : Locations showing the extent of plague epidemics in Europe during the Late Middle Ages and the Renaissance.
   4. subject - Keywords to the content.
      Ex. : history, plague, epidemics
   5. legend - Legends the colors and shapes of location markers on the map.
      1. themes - Array legending the colors. If this field is not filled the users might not be able to understand what features you represent by colors. See in the section "items > symbol" below for further details.
         Ex. : ["Unkown","Roses","Bananas","Grapefruits","Olives"]
      2. symbols - Legends of the shapes. See in the section "items > symbol" below for further details.
         Ex. : {"o":"Moon","u":"Earth","v":"Diamonds","t":"Cruzifix","x":"Pirates"}
   6. source - The source(s) from which the georeferences are extracted.
      Ex. : Jean-Noël Biraben, Les Hommes et la peste en France et dans les pays européens et méditerranéens, Paris/La Haye, Mouton/École des hautes études en sciences sociales, 1975-6.
   7. creator - The creator(s) of the file content.
      Ex. : Vlad Atanasiu, Claire Priol, Anne Tournieroux, Ezio Ornato
   8. publisher - The publisher(s) of the file content.
      Ex. : Project Bernstein: The Memory of Paper, http://www.memoryofpaper.eu
   9. rights - Legal right terms and rights holder.
      Ex. : Project Bernstein: The Memory of Paper, http://www.memoryofpaper.eu
   10. additional languages - Repeat the fields above between "contentLanguage" and "rights" with their content given in additional languages. Your map will become intelligible to a broader public, both local and international.
       You can select the language to be displayed by adding &lng=[language code] to the url, e.g. http://www.waqwaq.info/ws/main/main.html?url=http://www.self.com/georeferences.jsonp&lng=fr.
2. criteria - These fields are used in the case that the dataset represents a selection in a bigger one, such as an answer to a request in a database. The criteria used to define the selection are documented here. As an example are provided the criteria used by the Bernstein website, but the user can add any content to the field "criteria". Multiple entries are separated by comma (,).
   1. databases - Names of the databases in which the search was conducted (checkboxes checked in the search interface).
      Ex. : NIKI, POL, WILC, WZMA
   2. total - Total number of items in the database field on which the search is performed. I the query intersects several fields, "total" equals the quantity in the field with the least elements.
      Ex. : 67903
   3. matches - Number of hits for the search.
      Ex. : 2496
   4. term - Search term.
      Ex. : motif: Adler; dateStart: 1450; dateEnd: 1500; depository: Gdansk AA; height: 5; heightTolerance: 1; measurementUnit: cm; chainLines: 3; chainLinesTolerance: 0; laidLines: 20; laidLinesTolerance: 0.3; laidLinesUnit: mm / 20 laid lines; useplace: Rome; useplaceStatus: localities; localities and regions
3. spatial - Fields expliciting the spatial information contained in the file.
   1. boundingbox - The most extreme West, South, East, North coordinates values from the fields longitude, respectively latitude, in the present dataset. There is no space between the values, which are separated by commas (,) and use period (.) as decimal symbol.
      Ex. : -20.1,35,45,60.9
   2. coordinates - Coordinates format.
      Ex. : decimal degree
   3. nomenclature - Naming system used for the names of regions.
      Ex. : NUTS 2003
4. media - Information on the medium containg the content.
   1. encoding - File encoding.
      Ex. : UTF-8
   2. format - Data structure format, always JSONP.
      Ex. : JSONP
5. extra - Additional data deemed of interest to be added to the map legend.
6. created - Date the file was created.
   Ex. : 2009-08-03T01:14:35+02:00

Data

The geographical data is organized in items each representing a unique location with its attributes. Only the coordinates are a mandatory field, but supplying more information is always better for the users.

It is recommended to sort the items by descending order of records per item. This ensures that smaller markers on the map are kept visible by drawing them on top of bigger ones.

items - Contains information about each location.

1. status - Geometry of the place.
   Ex. : locality (represented as a point on the map), region (represented as a surface)
2. placename - Name of the place. If there are more than one placenames for a given location, it it suggested to use here one among them, as the "normalized" variant.
   Ex. : Roma (normalization of "Rome, Rom, ..."), Liguria (normalization of "Ligurien, ...")
3. latitude - Latitude expressed in decimal degrees.
   Ex. : 41.90
4. longitude - Longitude expressed in decimal degrees.
   Ex. : 12.48
5. regionId - Code given to the region in which the location appears. In Bernstein this is a NUTS 2003 region code.
   About NUTS: concise description in deutsch, english, français; official website; NUTS maps; NUTS 2003 nomenclature
   Ex. : ITE43, ITC33
6. country - Country name.
   Ex. : Italia
7. region1 - Name of the region inside the country.
   Ex. : Centro (I), Nord-Ovest
8. region2 - Subregion name.
   Ex. : Lazio, Liguria
9. region3 - Sub-subregion name.
   Ex. : Roma
10. region4 - Sub-sub-subregion region name.
11. records - Quantity of records for the current location. The records can denote the entities represented on the map, such as books or bananas. It includes the quantities supplied in field "uncertains".
    Ex. : 1248, 256
12. uncertains - Quantity of records among the total number of records given in field "records" for which it is not sure with absolute certainty that their location is the one give here.
    Ex. : 10, 1
13. theme - A numerical value identifying selected records as part of the same thematic class. Themes will be drawn in different colors. The values have to be positive integers within the range of the number of colors defined in the colormap. Higher values and no values are drawn with the first color in the colormap. If this field is missing the second color is used. Symbols are drawn by default with the second color in the colormap (theme number 1), the first one (theme number 0) being reserved for no or unkonwn values. Default support is for 5 themes. If more themes are needed the colormap has to be extented with new Red/Green/Blue values either in [this file's name].ini.js or site.ini.js (see MapSettings).
    Ex. : 4 to draw the features with the 5th color defined in the colormap.
14. symbol - The symbol for the shape that the specified record will take: o for a disk (default), u for a square, v for a rhomboid, t for a cross and x for an x. If this field is not supplied, 'disk' is assumed. This field can be defined for all, some, one or no records. Only the designated records will take the defined shape. This field overrules any other setting. Experiment with its impact on symbology before publishing your data.
    Ex. : o
15. extra - Additional data deemed of interest to be added to the location specific legend.

Lines

It is possible to link geographical objects with lines to represent some connection between them. The map below shows an example (live map here).

The lines can be toggled on and off by unclicking "lines" in map interface > symbols > links.

Procedure for enhancing the datafile to produce the links:

1. take a look at the sample data file
2. lines are drawn between points by creating new entries in the geodata file
3. there is a new entry for each line relying two points
4. the entry dedoubles in each field the content of the two entries that are to be connected...
5. with exception of the fields "records", "uncertainities" and "multiplaces", for which the content values is summed
6. the separator is " - " (space, dash, space)
7. records appear in descending order according to the value in field "records"

-- VladAtanasiu - 12 Mar 2009