This guide is for the older version of the PeriodO client hosted at https://test.perio.do/. If you are using the newer version of the PeriodO client hosted at https://client.perio.do/, see the new guide.
Browse the canonical dataset
The PeriodO client is an application that runs in your browser. It can be used to browse and edit any dataset that conforms to the PeriodO data model. But most people are probably interested in looking at the canonical dataset curated by the PeriodO project.
When you first load the client, you are prompted to select a backend. A backend is simply a location from which the client will load data. The client supports three kinds of backends:
A web backend loads data from a specified URL. Data loaded from a web backend can only be browsed, not edited.
A file backend loads data from a local file. Data loaded from a file backend is also browse-only.
An IndexedDB backend loads data from a local database running in your browser. Data in an IndexedDB backend can be edited as well as browsed. (Note that Safari does not yet have full support for IndexedDB.)
Initially you should see only one backend, a web backend pointing to the canonical PeriodO dataset (at
Clicking on the “disc with a down arrow” icon will download the data from the canonical web backend to a local file. Clicking on the name of the backend (“Canonical”) will load the data from the canonical backend into the client, and you should see a browsing interface like this:
Finding and comparing period definitions
In the browsing interface it is possible to find and compare period definitions by applying one of several filters (time range, source, language, spatial coverage) or searching by text string.
To filter by time range, on the right side of the browser window hover over the x-axis of the time range chart to find the desired ISO year. Drag your cursor to select a desired time range, and your selection will appear highlighted in gray in the time range. Period definitions which fall within this time range appear on the left side of the browser window under Periods, where you can view between 10 and 250 results at a time. Note that these results remain until you click back in the time range chart to reset the dataset.
To filter by source, locate the desired contributor in the Source box (which provides author, collection name, and year of creation/publication): these are listed in descending order by the number of periods contributed to the PeriodO dataset. You can also use
Ctrl+F to find a contributor by name. Clicking on the desired collection retrieves and displays all periods in that collection, and moves this collection to the top of the Source list. Clicking Reset on the right of the box causes the interface to display all records in the dataset again.
To filter by language, locate the desired language in the Language box: these are listed in descending order by the number of periods contributed to the dataset. You can also use
Ctrl+F to find a language by name. Clicking on the desired language retrieves and displays all periods entered in that language script, and moves this language to the top of the Language list. Clicking Reset on the right of the box causes the interface to display all records in the dataset again.
To filter by spatial coverage (geographic location), locate the desired location in the Spatial coverage box: these are listed in descending order by the number of periods contributed to the dataset. You can also use
Ctrl+F to find a spatial coverage by name. These terms reflect the labels used by the source to describe the period’s spatial coverage, NOT the coordinate-based geographic entity with which we have associated them. The large quantity of
undefined values reflect records that could clearly be associated with a modern national boundary, but for which the source did not provide a verbal label for spatial coverage (most of these are from Fasti Online and the British Museum). Clicking on the desired spatial coverage label retrieves and displays all periods associated with that label, and moves this term to the top of the Spatial coverage list. Clicking Reset on the right of the box auses the interface to display all records in the dataset again.
To search by text string, enter your text in the search box. Periods containing this text string will display on the left under the Periods list.
Results sets derived from filtering or searching can also be recursively filtered using all of the same methods as above, until only one result is left.
A results set can be ordered by label, earliest start, and latest stop, just like the full dataset. This is the simplest way to compare date ranges between period definitions. Clicking within any individual result expands the full period definition, including more detailed information including spatial coverage, permalink for the definition and its collection, and notes.
Getting structured data for a period collection
The entire PeriodO dataset can be downloaded as a JSON-LD file from the Switch backends page (click on the disk icon). You can also download any datasets you have created in a local database from this page as a JSON-LD file (see Creating a local database below). This can be very useful if you wish to share your period definitions with someone else, or if you need structured data for your own visualization or data management.
You can also view structured data for an individual collection from the page for that collection. At the top of the browser window, which shows Browse by Period by default, click the Browse by Collection tab. This will list all of the period collections.
Locate the desired collection (20 are currently viewable at once) by scrolling down or using
Ctrl+F, and clicking on the source title. This brings you to the page for this collection, which displays collection-level information at the top followed by individual period definitions below. These periods can be sorted by label, earliest start, or latest stop.
Finding and using a URI for a period or collection
Every period and collection that is part of the canonical dataset has been assigned a stable, permanent URI. When viewing the canonical dataset, if you are browsing by period, click on any period to expand the data display; this will show the permalink for the period.
Right-click or highlight to copy this link. Clicking on In collection will bring you to the collection page, at the top of which is the permalink for the collection. Right-click or highlight to copy this link.
Use PeriodO permalinks for citation and sharing: ensure that your period or collection URI from PeriodO always starts with
Creating a local database
! To edit periods and period collections, you must create a local database. To do this, first Switch backends, and then under Add backend select IndexedDB (editable, stored locally), write in a name for your local database, and click Add.
You should see your newly added IndexedDB backend appear in the list of backends. Click the name of your backend to switch to it.
Initially your new local database (the backend you just created) will be empty, to fill it with some period definitions, go to the upper-right Menu drop-down and select Get data from server or file.
Next you should see the Sync window. With
https://test.perio.do/ supplied as the server URL option, click Fetch which will retrieve all the period collections from the PeriodO server. From this list of New period collections, find your desired collection(s) and check the box to the left of their listing. Checking one or more boxes enables the Continue button at the top of the window. Click this button to confirm your selection.
The next screen displays your selected collections; ensure all that you need are listed and then under Accept changes? click Yes.
You have now made a local, editable database containing the periods in the selected collections. Next, at the top beside Current backend click switch to return to the backend selection page. Click on the name of your local database, and you will see a list of all the periods in the database. From here, you can click the Browse by Collection tab to make edits or additions. Click the collection you wish to edit. You will see the collection page, now with two new options to Edit collection details (this will edit the collection-level description) or Add period (to add a new period definition to this particular collection).
You can also edit existing periods: locate the desired period in the collection, click on its row to expand the data entry, and find the blue Edit button beside the period. Clicking on this button will open a form using which you can edit the period definition.
Once you have completed your edits, click the blue Save button at the bottom left and you will return to the collection. At any time, you can export your local database as a file by clicking switch at the top of the browser window to return to the backend selection screen, and clicking the “disc with a down arrow” icon to download the structured data as a JSON-LD file.
Sharing a local database
Once you have created a local database and downloaded it following the steps above, you can share your JSON-LD file with others. You can also make further edits to your JSON file(s), or edit a file that someone else has shared with you. Under the Menu button in the upper-right of the browser window, select Get data from server or file. Next, under PeriodO data file click Choose file and upload the JSON file you wish to load and edit. Once you see the data in your file, you can follow the steps above to edit your period collection and definitions.
Submitting a patch
We welcome contributions and enhancements (“patches”) to the canonical PeriodO dataset. To submit a patch, you must first register for a free ORCID so that we can credit you properly. Once you have an ORCID, click Sign in at the top of the browser window. You will see a link to Create or Connect your ORCID iD.
Clicking this link will open a popup window. From this window you can sign into the ORCID website and grant permission to PeriodO to read your public information (such as your name).
Once you are successfully signed in, you should see your name at the top of the PeriodO window. Now you can open a local database that has the changes or additions that you would like to contribute. Under the Menu button in the upper right of the browser window, select Submit patch to server and submit your patch. Check that your patch was successfully submitted by selecting Review patches (again, under Menu) to see a list of the patches submitted to server.