Logainm Application Programming Interface (Version 0.9): Developer documentation
Note: This documentation describes a prerelease version of the Logainm API. Features are being added on an ongoing basis. The documentation will be revised in advance of the v1.0 release.
- API overview
- API versioning
- API authentication
- Resource paths
- Illustrative examples
- HTTP status codes
- Data retention and data protection
The Placenames Database of Ireland was created by the Gaois research group at 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.
The Logainm API provides access to a number of resources by means of a defined URL schema. Specific resources are accessed via unique paths appended to the main website host. In some cases the resources that are returned may be filtered using optional query parameters. Attempts to access a resource provided by the API are referred to as requests. Following a successful request, resources are returned in the form of JSON. An unsuccessful attempt to access a resource will receive, at a minimum, a relevant HTTP status code in response to the request. An example of a valid request to the API is as follows:
Users or applications (clients) requesting a resource via the API must authenticate their identity. This is achieved by providing an API key with each request. Each client must obtain a unique API key prior to interacting with the interface. Authentication is required to prevent abuse of the service and to track general usage statistics. Further details are provided below.
Multiple API versions are facilitated. This is to say more than one version of the API may be accessible at the same time. Newer API versions may offer additional resources or functionalities but may require a different request syntax to older versions. The target API version is indicated by the second path parameter in the request URL:
Older versions will be supported for developer convenience: without versioning, frequent changes to API syntax might cause dependent client applications to malfunction. We will endeavour to add new resources incrementally and will implement breaking changes only as a last resort. The API is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification. For brevity, however, only major and minor version points are reflected in request URLs.
After a period of time it may become necessary to deprecate older API versions for maintenance or performance reasons. When you register for your API key, you will be asked if you are willing to receive communications from Fiontar & Scoil na Gaeilge from time to time. Agreeing to receive such communication means you will receive advance notice of any such changes.
Note: Prerelease versions of this API (i.e. < v1.0) are for testing purposes and will not be maintained once a v1.0 release has been reached.
Clients requesting a resource via the API are required to authenticate their identity. This is achieved by passing an API key to the service with each request. Authentication offers some protection to the service provider from abuse of the API involving request overloads. It also allows us to retain some usage statistics, with a view to performance monitoring and service enhancement. Learn more about the data we retain in the following sections.
How to obtain your API key
Visit the Gaois Developer Hub at gaois.ie. Log in or register to create an account and you will be able to access your unique API key.
Note: The registration service is coming soon. In the meantime, please contact us at firstname.lastname@example.org to request or reset your API key.
How to pass your API key
Your API key may be passed to the service in a few different ways. Choose whichever method is easiest for you.
Pass the API key into an
'X-Api-Key: <API_KEY_HERE>' 'https://www.logainm.ie/api/v0.9/1384618'
GET query parameter
Pass the API key into an
apiKey GET query string parameter:
Note: The GET query parameter may be used for non-GET requests (such as POST and PUT).
HTTP Basic Authentication username
As an alternative, pass the API key as the username (with an empty password) using HTTP basic authentication:
The API is served over a HTTPS protocol. Though HTTP requests to the service are automatically redirected to HTTPS, you should only ever interact with the API using HTTPS-prefixed URLs.
While HTTPS offers a signficant level of security, we would stress that the basic authentication methods described above do not amount to end-to-end encryption. You should only ever pass your API Key to the service—never include sensitive data, particularly passwords, as part of your requests.
The resources provided by the API are accessed via unique paths appended to the main website URL. All currently-available request paths are listed below. A data dictionary is available to assist users in parsing results returned by the API.
||General API metadata.|
||List of places and associated metadata.*|
||Metadata associated with an individual place.|
||Reference list of metadata associated with Irish administrative units. The unit identifers in this list can be used to filter places by
||Reference list of metadata associated with geographical features. The feature identifers in this list can be used to filter places by
||Reference list of words commonly found in Irish placenames and associated metadata. The glossary identifers in this list can be used to filter places by
||Reference list of metadata associated with counties. The place identifiers in this list can be used to filter places by
* Requests to the
/api/v0.9/ endpoint must be filtered by at least one of the following parameters:
GlossaryID, or a pair of
URL path parameters
URL query parameters
Use these query parameters to filter the results returned by the API.
||integer||Filter by place identifier. For example, a
||string||Filter by place category identifier, such as an administrative unit or geographical feature.|
||integer||Filter by glossary entry identifier.|
||boolean||If true, exclude places with a
||float||Filter by latitudinal coordinate. Must be used in conjunction with a
||float||Filter by longitudinal coordinate. Must be used in conjunction with a
||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.|
||integer||Specifies the radius size for a geographic query in metres. The maximum radius is 15000. Defaults to 3000 metres.|
||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
||boolean||If true, only return places which are in a Gaeltacht area. If false, exlude places in Gaeltacht areas from the result set.|
||boolean||If true, only return places in which there is or once was a post office. If false, exlude places in which there is or once was a post office from the result set.|
||boolean||If true, only return places which are in Northern Ireland. If false, exlude places which are in Northern Ireland from the result set.|
||ISO 8601 datetime||Retrieve records created before a given date in
||ISO 8601 datetime||Retrieve records created after a given date in
||ISO 8601 datetime||Retrieve records last updated before a given date in
||ISO 8601 datetime||Retrieve records last updated after a given date in
Where data relating to more than one place are returned in response to a query they are sorted by place identifier, in ascending order. The only exception to this are geographic queries, where the
Longitude query parameters are specified, in which case case places are listed in order of proximity to the specified coordinates, with the nearest places listed first.
Below is a non-exhaustive list of valid API request URLs, provided for demonstration purposes:
HTTP status codes
The status of all requests will be communicated, in the first instance, via standard HTTP status codes. We recommend that any applications interacting with the API handle the following status codes:
|200||OK||One or more JSON objects will be returned.|
|400||BAD REQUEST||The request syntax was invalid—a JSON object describing the error may be returned.|
|401||UNAUTHORISED||A valid API key was not provided.|
|404||NOT FOUND||The resource does not exist.|
|500||INTERNAL SERVER ERROR||Please contact us at email@example.com quoting the request path.|
Note: The current API does not handle create-, update-, or delete-type requests. Therefore, only HTTP GET methods are facilitated at this time.
Data retention and data protection
We store the following data every time a request is made to the API:
- Request path
- Response status code
- Result count
- Query response time
- Client ID (obtained with reference to the provided API key)
The client ID links your request to the data you have stored in the gaois.ie Developer Hub (the data you provided when you signed up for the service, for example). You can view all of the above data at any time in the Gaois.ie Developer Hub. These data are stored by Fiontar & Scoil na Gaeilge in a GDPR-compliant manner.
We reserve the right to report and/or publish aggregated or anonymised API query metrics. We will not report, publish or share any specific client data (i.e. your client ID or any associated client identification data) with any third party. We reserve the right to retain data items 1–4, listed above, indefinitely for the purposes of performance monitoring, research and service enhancement.
You are entitled to have your personal data removed from our systems at any time. This means deleting your username, password, name, organisational affiliation, and association with stored requests, completely and permanently. Please contact us at firstname.lastname@example.org if you wish to request that your personal data be removed.
By accessing the API you agree to abide by all policies and practices outlined in this document.