The Gaois research group in Fiontar & Scoil na Gaeilge, DCU, in collaboration with our project partners, is making a number of open data resources available to the public. These include RESTful Application Programming Interfaces (APIs) and other data artifacts. Each of these resources is released under specific licencing conditions: please read the appropriate licencing information, which accompanies the documentation for each resource on this website, before making use of the data.
The Logainm API is now in public beta release and provides programmatic access to the Placenames Database of Ireland. Another API for the Dúchas project is currently in advanced development and a prerelease version is now available. It is hoped to make further resources available in the future.
Gaois APIs share common usage, authentication, versioning and data protection patterns. The remainder of this document describes these patterns and should be read before proceeding to the specific documentation for each resource.
Gaois APIs provide 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 API request 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.
Gaois open data APIs support Cross-Origin Resource Sharing (CORS), meaning they can be used by client-side applications and in mobile browser environments.
Multiple API versions are facilitated for all of our REST APIs. This means that more than one version of each 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, 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 the Gaois research group from time to time. Agreeing to receive such communication means you will receive advance notice of any such changes.
Note: Prerelease API versions (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.
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.
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'
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).
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 significant 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 status of all API requests will be communicated, in the first instance, via standard HTTP status codes. We recommend that any applications interacting with our APIs 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.|
We store the following data every time a request is made to one of our APIs:
- 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 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 Developer Hub'. These data are stored by the Gaois research group, Fiontar & Scoil na Gaeilge, DCU 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 any of our APIs you agree to abide by all policies and practices outlined in this document.