Logainm Application Programming Interface (Version 0.9)

Note: The Logainm API is now in public beta release. While the v0.9 API is generally stable, breaking changes are possible in advance of a v1.0 release. We welcome feedback at gaois@dcu.ie.

Introduction

The Placenames Database of Ireland was created by the Gaois research group in Fiontar & Scoil na Gaeilge in collaboration with The Placenames Branch (Department of Culture, Heritage and the Gaeltacht). This is a comprehensive management system for data, archival records and placenames research conducted by the State. It is a public resource for Irish people at home and abroad, and for all those who appreciate the rich heritage of Irish placenames. The database has been accessible via the logainm.ie public website since 2008. This documentation describes a web-based Application Programming Interface (API) that exposes the database contents to programmatic queries. A data dictionary is available to assist users in parsing results returned by the API.

General API information

Please consult the getting started guide for Gaois open data resources before reading the rest of the documentation for the Logainm API. The getting started guide describes how to obtain your unique user credentials as well as providing important general usage information.

Resource paths

The resources provided by the API are accessed via unique paths appended to the main website hostname. All currently-available request paths are listed below. A data dictionary is available to assist users in parsing results returned by the API.

Method Path Resource
GET /api General API metadata.
GET /api/v0.9 List of places and associated metadata.*
GET /api/v0.9/{id} Metadata associated with an individual place.
GET /api/v0.9/administrative-units Reference list of metadata associated with Irish administrative units. The unit identifiers in this list can be used to filter places by CategoryID.
GET /api/v0.9/features Reference list of metadata associated with geographical features. The feature identifiers in this list can be used to filter places by CategoryID.
GET /api/v0.9/glossary Reference list of words commonly found in Irish placenames and associated metadata. The glossary identifiers in this list can be used to filter places by GlossaryID.
GET /api/v0.9/counties Reference list of metadata associated with counties. The place identifiers in this list can be used to filter places by PlaceID.

* Requests to the /api/v0.9/ endpoint must be filtered by at least one of the following parameters: PlaceID, CategoryID, GlossaryID, or a pair of Longitude and Latitude parameters.

URL path parameters

Name Type Description
id integer Resource ID.

URL query parameters

Use these query parameters to filter the results returned by the API.

Name Type Description
PlaceID integer Filter by place identifier. For example, a PlaceID of 100013 returns all of the places in County Donegal.
CategoryID string Filter by place category identifier, such as an administrative unit or geographical feature.
GlossaryID integer Filter by glossary entry identifier.
ExcludeStreets boolean If true, exclude places with a CategoryID of SR (streets) from the result set. Streets can add greatly to the size of the result set and, consequently, the response time when querying places that include large urban areas.
Latitude float Filter by latitudinal coordinate. Must be used in conjunction with a Longitude value.
Longitude float Filter by longitudinal coordinate. Must be used in conjunction with a Latitude value.
Accurate boolean If true, only return places whose geographic coordinates are believed to be precise. If false, only return places whose geographic coordinates were obtained by extrapolation from neighbouring places.
Radius integer Specifies the radius size for a geographic query in metres. The maximum radius is 15,000. Defaults to 3,000 metres.
Query string Filter by search term(s). Textual searches are accent sensitive, for example, the search terms 'Rath' and 'Ráth' each return different sets of results. Note that textual searches currently only retrieve exact matches for query terms. Partial or speculative matches may be detailed in the SimilarNames response field.
Gaeltacht boolean If true, only return places which are in a Gaeltacht area. If false, exclude places in Gaeltacht areas from the result set.
PostOffice boolean If true, only return places in which there is, or once was, a post office. If false, exclude places in which there is, or once was, a post office from the result set.
NorthernIreland boolean If true, only return places which are in Northern Ireland. If false, exclude places which are in Northern Ireland from the result set.
CreatedBefore ISO 8601 datetime Retrieve records created before a given date in YYYY-MM-DD format.
CreatedSince ISO 8601 datetime Retrieve records created after a given date in YYYY-MM-DD format.
ModifiedBefore ISO 8601 datetime Retrieve records last updated before a given date in YYYY-MM-DD format.
ModifiedSince ISO 8601 datetime Retrieve records last updated after a given date in YYYY-MM-DD format.

Sorting

Where data relating to more than one place is returned in response to a query it is sorted by place identifier, in ascending order. The only exception to this are geographic queries, where the Latitude and Longitude query parameters are specified, in which case places are listed in order of proximity to the specified coordinates, with the nearest places listed first.

Illustrative examples

Below is a non-exhaustive list of valid API request URLs, provided for demonstration purposes:

  • https://www.logainm.ie/api/v0.9/?PlaceID=100013
  • https://www.logainm.ie/api/v0.9/?PlaceID=100009&CategoryID=PAR
  • https://www.logainm.ie/api/v0.9/?PlaceID=100002&ModifiedSince=2019-01-01
  • https://www.logainm.ie/api/v0.9/?PlaceID=100001&CategoryID=SRB&ModifiedSince=2017-01-01
  • https://www.logainm.ie/api/v0.9/?Latitude=53.3693445&Longitude=-6.271958104774972&Radius=10000&CategoryID=PAR
  • https://www.logainm.ie/api/v0.9/?GlossaryID=58
  • https://www.logainm.ie/api/v0.9/?PlaceID=100024&Gaeltacht=true
  • https://www.logainm.ie/api/v0.9/?PlaceID=100010&ExcludeStreets=true
  • https://www.logainm.ie/api/v0.9/?Query=Carrick&PlaceID=100029
  • https://www.logainm.ie/api/v0.9/1412322
  • https://www.logainm.ie/api/v0.9/1411548
  • https://www.logainm.ie/api/v0.9/14448
  • https://www.logainm.ie/api/v0.9/1384618
  • https://www.logainm.ie/api/v0.9/26783
  • https://www.logainm.ie/api/v0.9/1375542
  • https://www.logainm.ie/api/v0.9/2425
  • https://www.logainm.ie/api/v0.9/administrative-units/
  • https://www.logainm.ie/api/v0.9/features/
  • https://www.logainm.ie/api/v0.9/glossary/
  • https://www.logainm.ie/api/v0.9/counties/
Gaois

Our apologies

This website is not compatible with the Microsoft Internet Explorer web browser. Please use Chrome, Edge, Firefox, Opera, or another modern browser to access the website content.

Contact us at gaois@dcu.ie if you have any questions.