One of the most useful and popular aspects of TLCMap is the web services API. Check the details in the Guide. It enables you to:

• Query the most comprehensive aggregate gazetteer of Australian place names, including many historical place names.
• Query and access data in user contributed layers.

Typically TLCMap web applications use GET parameters for ease of interoperability and integration. For example, you may notice some of the visualisations use such parameters which you could use to link generate and link to your own visualisations.

The following, simple but important, easy but powerful, points will enable TLCMap systems and projects to work together as a cohesive whole rather than be a set of disparate research, development and humanities projects. These are all indicated as ‘should’ rather than ‘must’ as the diversity of areas of development means in reality some of these points may not be applicable. While some of these points may seem obvious and desirable and should be standard practice, there are many cases in which they are not implemented so it’s worth stipulating.

All TLCMap projects should, where feasible and allowable:

• No infrastructure without projects. No system should be built without projects to demonstrate usefulness.
• No project without infrastructure. No project should be undertaken unless it is using software that can be re-used for similar projects.
• Import/Export in standard formats. All systems should enable import and export of spatiotemporal data in standard formats such as KML, GeoJSON, JSON-LD, CSV, ROCrate and other relevant standards.
• Layers. Systems should allow import/creation/visualisation/use of more than one dataset at a time.
• Web Services. Systems should expose information through RESTful web services APIs for potential re-use in other developed systems.
• Public, private, group permissions. All systems should enable at least these privacy settings for people to work comfortably and collaboratively, and make information available if and when ready.
• All Dates. It should be possible to import dates in any of these formats: YYYY; YYYY-MM-DD; DD/MM/YYYY, where any number of Y digits are allowable, and dates before BC are expressed with a minus sign. A 0 may or may not be included in the year for dates between 1000BC and AD. Eg: 10,000BC would be -10000. The 1st of April in the year 786AD would be 01/04/786, or 01/04/0786. Dates in data export may be in either YYYY-MM-DD or DD/MM/YYYY format. Web services should follow conventions in the ISO 8601 Date and Time Formats specification.
• All entities should have unique URLs. All relevant entities within a system should be uniquely addressed with a URL. Through a web service the URL returns relevant data for that entity. Through user interfaces the application should ‘zoom’ to or load the entity when the URL is visited in the browser. What a relevant ‘entity’ is depends on the context and application. Eg: it may be a place on a map, a word in a text, an image, a section of an image etc.
• Entity URLs in exported data. Data exported or made available through a web service should include the URL of the entity/record in the system exported from. This enables data to work among all compliant systems, eg: I am viewing a dataset in a time visualisation with other datasets – my dataset was created in a text analyser. While in the time visualiser, I can still directly access the relevant text for this point, by clicking the link to it that goes to the text analyser.
• Entity URL chaining. Where feasible, data imported and exported should not overwrite existing entity URLs, but add to a list of URLs from other systems. This enables linking among many systems through which the information has passed.

• Systems developed should enable import and export of data in standard geodata formats, particularly KML, GeoJSON and CSV. Systems should handle point line and polygon data in these formats, and at minimum a start date and end date for each ‘feature’.
• Systems should allow for importing and/or creating more than one dataset or ‘layer’.
• If development requires data structures that don’t fit within standard geodata formats, more general standard data formats should be used, such as XML and JSON.
• If using KML with extra data for features, the extended data should be marked up as HTML in the ‘description’ field, within a div tag with a class indicating its origin or purpose. This should be used in contrast to the extended data fields that would at first glance seem ideal for this purpose. The reason is that extended data overrides display of ‘description’ field in many systems, such as Google, so that this content intended for human readability is not accessible. It is too limited in terms of the data that may be entered, described and structured. Features to enable extending its capability are complicated and onerous and would take extra custom effort in consuming systems to handle. Marking up extended data as HTML in CDATA in the description tag enables more structure with trees, identifiers, attributes, classes and links, in a way that is easily human readable and easy for developers to handle in consuming systems with CSS and Javascript. (eg:<description><![CDATA[<div class=”tlcmap”><p id=”name” class=”personmetadata”>Mary Shelley</p></div>]]></description> )

It is important in humanities that any date can be used, and it can be a reason not to use software if it cannot handle any potential date. TLCMap recommends following conventions in the ISO 8601 Date and Time Formats specification XML Schema Part 2: Datatypes Second Edition. This convention is adopted by the KML specification (see Compliance point above).

Times should follow the ISO 8601 format of hh:mm:ss.sss or Thh:mm:ss.sss (with all parts after hh being optional).

A common problem when dealing with dates is the use of different date formats by different countries and by software systems. US dates are often in the format MM/DD/YYYY, with the month at the beginning. A lot of software is developed in the USA so this is sometimes the default setting and assumption. This can lead to a lot of confusion as we move date information around systems, as the 1st of April can easily be changed to the 4th of January without us noticing. It is usually possible to change default software settings to a region with an unambiguous format such as DD/MM/YYYY or YYYY-MM-DD. Because US dates cannot be automatically disambiguated based on their format, TLCMap systems don’t make allowances for US dates, unless it is already built in to a system we are using or adding to. Users should convert date formats before data import.

Another common problem is that many databases, and so the software systems built on them, have a ‘date’ datatype that does not go back very far into the past. They often cannot handle dates with three numbers in the year, such as the 1st of April in the year 786 (786-04-01 or 01/04/786), or BC dates. These problems can be worked around by software developers, by using a text field and adding code for input validation, but it requires effort. Because it is crucial for many humanities projects, in TLCMap software we try to ensure any date can be entered.

TLCMap systems should support several formats of date:

NOTE: For all of these formats a hyphen can be used as a minus sign for BC dates. It must allow for use of 0s to infil, or less that four digits. (eg: 12BC could be -0012 or -12. 10,000BC would be -10000).

• YYYY: Often, the year is the only date information a person has, and it is onerous and misleading to add MM/DD to it, such as to indicate every such date as 01/01 of that year. However, some systems cannot function without the DD/MM part of the date. If this is the case the suggested work around is to use a timespan that begins YYYY-01-01 and ends YYYY-12-31. If only a single date can be used, use YYYY-01-01.
• YYYY-MM-DD: This is the preferred date format, compatible with ISO 8601. It is clear, unambiguous and easy to sort.
• DD/MM/YYYY: Some systems, notably MS Excel which is likely to be used for CSV files, automatically converts dates in other formats into this format, such as when saving as CSV. It would be deeply frustrating to the user to try to find ways to modify this. For this reason, this additional format should be supported.

KML and GeoJSON

When outputting KML it is recommended to use timespans rather than timestamp elements. Even if you are representing a point in time, set the begin and end to be the same date-time. This allows for expression of vagueness or bounds within with something may have occured. Vagueness is always highlighted by humanities researchers using software that usually expects precision.

GeoJSON and the JSON community has not adopted a convention for describing time in association with place. In many cases, there is a simple requirement for a begin and end date as in the KML timespan element (which can be set the same for a point in time). There are several solutions to this proposed on the internet. TLCMap recommends simply adding a begin and end attribute to the properties is recommended. Eg:

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [125.6, 10.1]
  },
  "properties": {
    "name": "Dinagat Islands",
    "begin": "2020-11-01",
    "end": "2020-11-30"
  }
}

Other Temporal Structures

There are many temporal structures that cannot be expressed with a simple begin and end date, and which require unique data structures for storage and communication, and visualisation alternatives to conventional timelines. We anticipate that with continued funding TLCMap will propose conventions for the mark up of these. KML is constrained, but GeoJSON and JSON are flexible enough to allow for these developments.

Temporal structures to be considered are:

Journey

A series of points in a line visited at various dates and times. This is distinct from ‘ordinal’ time (below), where we describe a series of places that may be visited in order, as on a journey, but not at any particular date or time.

Examples: as a ship visiting different ports at different times, recording it’s coordinates at various times in its log. a person travelling around.

Migration

Movements of certain amounts from place to place at different times. This is distinct from a journey in that we are interested in the amount of something moving from place to place over time.

Examples:

How many people migrated from each country in the world through each decade of the 20th century, arriving at which cities?

Frontier

A line or polygon that moves over time.

Examples:

The Western Front in World Wars I and II.

The area being burned by a bushfire.

Stationary

Places that don’t move but change in various ways over time. The properties or attributes of things may change in a way that can be visualised, or analysed.

Example:

Over time cinemas in a city are in buildings that don’t move, but may open and close, change their ownership, their audience numbers decrease and increase and they might start or stop showing different types of film.

Cyclical

Repeated events which occur at regular intervals. Cyclical time can be quick complex with cycles within cycles and overlapping phases.

Examples:

Festivals and rituals that occur at different seasons or times of the year, or every few years, such as east coast Aboriginal peoples tending to move inland to cooler highlands for hunting in summer and to the coast for fishing in winter, and attending the Bunya festival every three years.

Ordinal

A series of steps that occur in a specific order but not any particular time.

Example:

Instructions to go from one place to another (go down the road to the intersection, turn left until you reach the shop, then go to the end of the bridge near the big tree, etc)

The order in which places are mentioned in a book or set of newspaper articles.

Calendar

Events which occur on a particular date or time.

Examples:

Appointments made in your journal or booking system. Calendaring is probably the most well implimented temporal concept in IT but in humanities we may be also be concerned with complicated issues with alternative calendaring systems, such as the French Republican calendar, or the ancient Mayan calendar.

Space Time Warping

Distance can be thought of not only spatially but temporally, or a combination of both. The distance from one place to another, is sometimes recorded in travel time, rather than kilometres for example. Maps can be ‘warped’ to visualised distances according to time rather than space. Bear in mind that travelling in one direction may take longer or shorter than travelling back (such as travelling with or against prevailing winds and currents).

Examples:

Medieval itineraries, or travel guides, indicate how long it will take to get to each point on a journey, which is important for provisioning.

Features to get direction in online trip planners usually indicate travel time as well as distance.

Certain kinds of maps such as isochrones can depict travel time by indicating radiating regions or by distorting spatial relations.

The following areas present their own set of technical and theoretical difficulties so can be treated as areas of development and enquiry, though all of the above ways of thinking about time may apply.

Eco-geological

Representing ecological factors or change at the scale of geological time can

Examples:

Representing changing coastlines.

Showing ecological zones that would exist without human habitation, or how they change over millenia.

VR Time

Space and time are fundamental to creators and users of VR, even at the most basic levels, such as the speed at which the user moves. Reconstructing places and objects from history or for heritage are common interests for Humanities VR, and various ways of visualising changes in those things over time presents challenges.

Examples:

Controls for moving around VR environments.

Constructing historical buildings or game environments for people to move through.

If you are a digital humanist or a developer new to mapping technology, here’s a few places to start and technologies to be aware of:

• GIS open standard and common data formats: KML, CSV, GeoJSON, Tiled Image formats, Shapefiles
• LeafletJS, CesiumJS
• ArcGIS Javascript API and Google Javascript API
• Gephi, D3, R
• GeoDjango
• QGIS
• Pelagios / Recogito
• OpenLayers, Open map servers, WMS, WFS, WCS, PostGIS, Map Tile Server
• Heurist
• Omeka
• IIIF and Open Seadragon
• Named Entity Recognition (NER)
• Open Street Map
• Python Folium, Jupyter Notebooks
• MapWarper
• AV controls in Javascript and HTML
• Mass indexing
• Embed and AJAX
• Web Services, RESTful JSON
• Quantitative data visualisation on maps