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.
This document describes the data structure of the results made available via the Logainm Application Programming Interface (API). Logainm is a comprehensive management system for data, archival records and placenames research conducted by the Government of Ireland. For general information regarding the API and for developer guidelines please consult the developer documentation.
Most API queries will return a placeList
object. This contains a list of one or more places, if found, and additional metadata related to the query.
Property name | Type | Cardinality | Description |
---|---|---|---|
TotalCount | integer | one | The total count of place records retrieved. |
TotalPages | integer | none or one | If the place list is paginated, the total number of pages in the result set. |
CurrentPage | integer | none or one | If the place list is paginated, the current page number. |
CountPerPage | integer | none or one | If the place list is paginated, the maximum count of results returned per page. |
Places | place |
none or one or many | The retrieved place records. |
SimilarNames | string | none or one or many | A set of names which have a similar spelling to the query text (if performing a textual search). For example, if searching for 'Ballybunion', 'Ballybunnion' will be suggested. |
RelatedNames | string | none or one or many | A set of names which are related to the query text (if performing a textual search). For example, if searching for 'Lismore', the list of related names will suggest 'Lismore and Mocollop', 'Lismore Demesne', agus 'Lismore Road'. |
The place
object is at the core of the Logainm API: it represents a geographic location and includes associated toponymic, lexical, and other metadata. Queries specifying a place identifer in the request path will retrieve a single place
object (if one exists) while broader queries may return one or more place
objects in the response body.
Property name | Type | Cardinality | Description |
---|---|---|---|
ID | integer | one | The unique place identifier. |
ReplacementID | integer | none or one | If this value is set the requested place record has been merged into another record in the database. The value is the replacement record identifier. |
DateCreated | ISO 8601 datetime | one | The date and time of entry creation. |
DateModified | ISO 8601 datetime | none or one | The date and time of most recent modification to entry. |
Permalink | string | one | A permanent static hyperlink where a human reader can find more information about the place. This automatically redirects to the Irish or English version of the place information page. |
Featured | ISO 8601 datetime | none or one or many | Denotes the date or dates on which this place was featured as the place of the day on the logainm.ie website, if featured. |
Cluster | cluster |
none or one | Metadata representing a group of places, of which this place is a member, that share placenames and are colocated or are proximate to each other. |
Placenames | placename |
one or many | One or more placenames, and associated metadata, that are given to this place. |
Glossary | glossary |
none or one | Describes words commonly found in Irish placenames and that are present in placenames associated with this place. |
Categories | category |
none or one or many | Describes the categories associated with this place. Only in exceptional cases will places have more than one category. |
IncludedIn | placeSummary |
none or one or many | Summary information regarding the administrative units (counties, civil parishes, etc.) which include this place. |
Includes | category |
none or one or many | Describes the place categories included within the bounds of this place. |
Geography | geography |
none or one | Geographical location of the place expressed in terms of latitudinal and longitudinal coordinates. |
GridReferences | gridReference |
none or one or many | Geographical location of the place expressed in terms of Irish Grid Reference System coordinates. |
Gaeltacht | placeProperty |
none or one | Indicates whether the place is in the Gaeltacht. |
PostOffice | placeProperty |
none or one | Indicates whether there is or was once a post office in this place. |
NorthernIreland | placeProperty |
none or one | Indicates whether this place is in Northern Ireland. |
Images | image |
none or one or many | Describes one or more scanned records from the Placenames Branch archive relating to this place. |
Resources | resource |
none or one or many | Describes one or more toponomy resources available on logainm.ie relating to this place. |
Links | link |
none or one or many | Provides one or more links to related data in external resources. External resources include OSI, Placenames Northern Ireland, Wikipedia, Geonames, etc. |
BornHere | biographyLink |
none or one or many | Provides links to biographical data from ainm.ie for any persons born in this place, if available. |
Folklore | folkloreLink |
none or one or many | Provides links to folkloric data from dúchas.ie associated with this place, if available. |
SameAs | sameAs |
none or one or many | Specifies one or more co-references to this place in data sets other than the Placenames Database of Ireland. Consistent with OWL Web Ontology SameAs definition. |
Metadata representing a group of places that share placenames and are colocated or are proximate to each other.
Property name | Type | Cardinality | Description |
---|---|---|---|
FocusID | integer | one | Identifies the place that forms the 'focus' of the cluster. It may represent the place category most readily associated with a particular placename or feature the richest set of metadata among all the cluster members. |
Members | clusterMember |
one or many | Represents the individual places that make up the cluster. |
Represents a member of a cluster
.
Property name | Type | Cardinality | Description |
---|---|---|---|
PlaceID | integer | one | The place identifier. |
Category | category |
none or one | The place category. |
Describes a toponym associated with one or more places.
Property name | Type | Cardinality | Description |
---|---|---|---|
ID | integer | one | The placename identifier. |
Language | ISO 639-1 language code | none or one | Indicates the language of the placename, if known. |
Wording | string | one | The placename itself. |
Genetive | string | none or one | In the case of Irish-language placenames this specifies the placename's grammatical form in the genitive case. |
Main | boolean | one | If true this is the place's main/canonical name. This is only important if the place has more than one name in the same language. |
Acceptability | acceptability |
none or one | Indicates the research and approval status of the placename. |
Audio | audio |
none or one | Describes an audio file providing an indicative pronunciation of the placename. |
SubNames | subName |
none or many | A list of two or more discrete placenames. Provided when the parent placename is composed of two more or more names that are conjoined, e.g. Rathgarvan or Clifden, or when part of the parent placename fulfils a qualifying or disambiguating role. |
Indicates the research and approval status of a placename.
Property name | Type | Cardinality | Description |
---|---|---|---|
ID | integer | one | The acceptability status identifier. |
TextEN | string | none or one | An English-language label describing the acceptability status. |
TextGA | string | none or one | An Irish-language label describing the acceptability status. |
Describes an audio file providing an indicative pronunciation of a placename.
Property name | Type | Cardinality | Description |
---|---|---|---|
FileName | string | one | The audio file name. |
Uri | string | one | The audio file URI. |
A discrete name which may used in composing longer placenames.
Property name | Type | Cardinality | Description |
---|---|---|---|
Text | string | one | The text of the name. |
Disambiguates | boolean | one | If true, this name provides some form of disambiguation in respect of the parent placename. A disambiguating subName might, for example, distinguish the parent placename from other, similar names. |
Summary information regarding a particular place.
Property name | Type | Cardinality | Description |
---|---|---|---|
ID | integer | one | The place identifier. |
NameEN | string | none or one | The English-language placename. |
NameGA | string | none or one | The Irish-language placename. |
Category | category |
none or one | The place category. |
Expresses a geographical location in terms of latitudinal and longitudinal coordinates.
Property name | Type | Cardinality | Description |
---|---|---|---|
Accurate | boolean | one | Indicates whether the coordinates are believed to be precise. Inaccurate coordinates are those that have been obtained by extrapolation from neighbouring places. |
Coordinates | coordinates |
one or many | One or more pairs of latitudinal and longitudinal coordinates. Most places are represented by a single pair of coordinates. However, certain geographical features, such as rivers or islands, in particular, may have two or more pairs. |
Represents a pair of geographic coordinates.
Property name | Type | Cardinality | Description |
---|---|---|---|
Latitude | double | one | The latitudinal coordinate. |
Longitude | double | one | The longitudinal coordinate. |
Expresses a geographical location in terms of Irish Grid Reference System coordinates.
Property name | Type | Cardinality | Description |
---|---|---|---|
Square | string | one | Specifies the grid square. |
Easting | long | none or one | Specifies the easting in the square. |
Northing | long | none or one | Specifies the northing in the square. |
Describes a property of a particular place.
Property name | Type | Cardinality | Description |
---|---|---|---|
Extent | string | one | Specifies the extent to which the property applies to a particular place. If all , the property applies to the whole place. If part , the property only applies to some of the place. |
Describes a scanned record from the Placenames Branch archive.
Property name | Type | Cardinality | Description |
---|---|---|---|
FileName | string | one | The image file name. |
LabelEN | string | none or one | An English-language description of the image category, if known. |
LabelGA | string | none or one | An Irish-language description of the image category, if known. |
Uri | string | one | The image URI. |
Describes a toponomy resource available on logainm.ie.
Property name | Type | Cardinality | Description |
---|---|---|---|
ID | integer | one | The resource identifier. |
TypeID | string | one | Identifies the resource type. |
TitleEN | string | none or one | The resource's English-language title. |
TitleGA | string | none or one | The resource's Irish-language title. |
PageReference | string | none or one | Specifies the page or pages within the resource associated with a particular place, if applicable. |
Supplier | supplier |
none or one | Metadata regarding the publisher/supplier of the resource. |
This possible values of the TypeID
property are as follows:
Value | Description |
---|---|
jpg | A JPEG image. |
A PDF document. | |
zip | A ZIP file. |
Metadata regarding the publisher/supplier of a toponmy resource.
Property name | Type | Cardinality | Description |
---|---|---|---|
ID | integer | one | The supplier identifier. |
NameEN | string | none or one | The supplier's English-language name. |
NameGA | string | none or one | The supplier's Irish-language name. |
Provides a link to related data in an external resource.
Property name | Type | Cardinality | Description |
---|---|---|---|
Type | string | one | The external resource type. External resources include OSI, Placenames Northern Ireland, Wikipedia, Geonames, etc. |
Target | string | one | The link target. This may be a URI, URL, or other identifier, depending on the resource type. |
This possible values of the link type property are as follows:
Value | Description |
---|---|
Geonames | The link is a URL for a Geonames entry. |
Osi | The link is an Ordnance Survey Ireland resource identifier. |
PlacenamesNi | The link is a Placenames Northern Ireland resource identifier. |
WikipediaEn | The link is a URL for an English-language Wikipedia entry. |
WikipediaGa | The link is a URL for an Irish-language Wikipedia entry. |
Provides links to biographical data from ainm.ie for any persons born in a particular place.
Property name | Type | Cardinality | Description |
---|---|---|---|
ID | integer | one | The biography's ainm.ie identifier. |
Title | string | one | The biography title. |
Uri | string | one | The URI for the ainm.ie biography. |
Provides a link to folkloric data from dúchas.ie associated with a particular place.
Property name | Type | Cardinality | Description |
---|---|---|---|
Type | string | one | The external resource type. At present this will always describe resources from the Dúchas project. |
UriEN | string | one | The URI for the folkloric data resource (English-language interface). |
UriGA | string | one | The URI for the folkloric data resource (Irish-language interface). |
Specifies a co-reference to a particular place in data sets other than the Placenames Database of Ireland. Consistent with OWL Web Ontology SameAs definition.
Property name | Type | Cardinality | Description |
---|---|---|---|
Uri | string | one | The URI of the external resource. |
Describes a place category. Categories encompass both administrative units and geographical features. One or more categories may be returned as part of a place
object or a reference list of category
objects may be obtained from the appropriate API endpoint.
Property name | Type | Cardinality | Description |
---|---|---|---|
ID | string | one | The category identifier. |
NameEN | string | none or one | The English-language category name. |
NameGA | string | none or one | The Irish-language category name. |
NamePluralEN | string | none or one | The English-language category name plural form. |
NamePluralGA | string | none or one | The Irish-language category name plural form. |
Count | integer | none or one | The number of placenames associated with this category, if known. |
Describes a set of related words commonly found in Irish placenames. One or more glossary entries may be returned as part of a place
object or a reference list of glossary
objects may be obtained from the appropriate API endpoint.
Property name | Type | Cardinality | Description |
---|---|---|---|
ID | integer | one | The glossary entry identifier. |
Headword | string | one | The glossary entry headword. |
Translation | string | none or one | An English-language translation of the glossary headword. |
Forms | string | none or one or many | Alternate spellings of the glossary headword. |
Count | integer | none or one | The number of placenames associated with this glossary entry, if known. |