How can I use NZOR?
The fundamental question is “why should I want to use NZOR?”
Many organisations have databases and documents which refer to the names of organisms. NZOR provides a means for standardising their use so that we meaningfully communicate about organisms at the national level (and internationally). One name can apply to several organisms and one organism can have several names. In addition, the sometimes complex relationship between names and the organisms to which they apply can change over time. Thus we need a way of standardising the way we refer to names and we need to be able to know if the relationships change. In all practical applications we use ‘name strings’ to refer to an organism. An example would be “Blue penguin” as a common name, and/or “Eudyptula minor” as the equivalent scientific name. Somebody recording penguin populations might capture “Blue Penguin” as a string in a spreadsheet cell. In many cases this way of referring to an organism is unambiguous, but there are also many exceptions. An example from another domain would be the Inland Revenue. Your name is used to narrow down who you are when you ring up. However, your name almost certainly won’t be unique when we include everybody in New Zealand. Consequently you will have a guaranteed unique IRD number which is linked to your name. The record management systems within the IRD and your employer ‘know’ who you are by referring to that number, and not your name. NZOR is intended to provide the same service. Every name is linked to a unique identifier, and the linkages between names and their applications are maintained through these identifiers and not the name itself. You might think it would be far simpler if we just all agreed to use the same set of standard name strings. There are many reasons why that approach (tried many times) does not work and our ‘record management systems’ need to use unique identifiers.
This does not mean that your organisation needs to adopt NZOR 'name strings', or even NZOR identifiers to manage data, just as the Personnel Department in your organisation is unlikely to be using IRD numbers to identify staff. You are free to use whatever list of names and/or identifiers you want. However, if you wish to communicate beyond your organisation, then you need to translate to the national standard provided by the NZOR identifiers. The simplest approach to solving this problem is to build and maintain a local dictionary of names your organisation uses, and mandate the use of that dictionary within your data capture/management systems. In that way your are standardising your internal use of names, and there is just one central list of names that needs to be matched and linked to the equivalent entries in NZOR. If you have no control over what names are supplied to you then the matched and linked to NZOR as that data is brought into organisation level information systems.
Matching arbitrary list of names against NZOR is rarely a straightforward process. The entries are likely to be common names or scientific names, and in either case the form and spelling of those names will vary (if a species dictionary was not used at the point of data capture). Just to re-iterate, there is no internationally agreed standard way of writing common or scientific names, nor is there ever likely to be. The average list of names usually contains at least 30% spelling errors, even for scientific names entered by knowledgeable editors. This first step in linking your organisation’s standard list, or an arbitrary list of names to NZOR, is to use the NZOR matching service. An example of the NZOR matching services is provided by this website, but note, like all other components of NZOR it is driven by web-services intended to be invoked through data management systems within your organisation.
The returns from the matching process contain all the likely 'hits' between the string you provided and the entries in NZOR. Because of variability in the way people write and splle names there may rarely be an exact hit with NZOR. More often than not it will require human intervention to make the final decision on the correct linkage, and any corrections that need to be applied to local name strings (if required). The match return also contains some basic information about the information NZOR has on that name. However, the most important part of the NZOR match is the NZOR GUID (Globally Unique Identifier). Once you know the NZOR GUID for a name string then it becomes a simple process using the NZOR web services to extract all the information known about that name.
This website provides some examples of using the NZOR web-services, but to maximise the benefit will require the development of local information systems to directly use those web-services.
The documentation describing those web-services.
The end-point of the NZOR Data Service.
Example web-service call: https://data.nzor.org.nz/names/search?query=Amphioxi
An example application using NZOR services
The search and match functionality in this website using NZOR web-services