Supporting SNAPP: Accessing New Zealand Medicines Terminologies With FHIR Terminology Services

A guest post from Peter Jordan – author of the Patients First Terminology server that will be available for use at SNApp, and frequent HL7 FHIR Connectathon attender…

Take it away Peter…

As those developing healthcare applications for the local market are well aware, and overseas developers preparing for the ‘SNAPP’ event at the upcoming SNOMED conference in Wellington, are becoming aware, New Zealand has its own medicines terminology. Interacting with this terminology – broadly known at the NZ Universal List of Medicines (NZULM) – is one of the many challenges facing SNAPP participants.

In common with the self-deprecating slogan used to advertise a local soft drink, NZULM happens to be ‘world famous in New Zealand’, but little known outside the ‘Shaky Islands’. Therefore, in the interests of levelling the playing field for all contestants (and there is prize money at stake here), this post is a brief introduction to NZULM and how one may interact with it using a Terminology Services API based on…no surprises to readers of this Blog…FHIR.

While NZULM shares some similarities with SNOMED CT (SCT-compatible identifiers, fully-specified names and preferred terms), to date it has not been designed as a SNOMED-CT national drug extension and therefore, not instantly accessible through the Implicit Value Set syntax that FHIR offers for accessing SNOMED CT.

In fact NZULM consists of several components, the main one – particularly for this purpose – being the NZ Medicines Terminology (NZMT). In FHIR parlance, one might describe this as the Code System. In relational database terms, this consists of a large number of tables, but the key objects are those designed to hold the seven distinct “product concepts” – collectively known as the “Seven Boxes”:

MP Medicinal Product

Generic substance.

Eg: Paracetamol.

May refer to a complex product containing multiple substances.

Eg: Paracetamol + Codeine.

MPUU Medicinal Product Unit of Use

Generic substance formulation including dose size and dose form.

Eg: Paracetamol 50mg Tablet.

MPP Medicinal Product Pack

Generic substance pack size. Generally treated as an Abstract concept.

Eg: Paracetamol 50mg Tablet, pack of 20.

TP Trade Product

A branded product

Eg: Panadol

Eg: Panadol Night and Day (complex pack)

TPUU Trade Product Unit of Use

A branded product formulation including dose size and dose form.

Eg: Panadol 50mg Tablet

TPP Trade Product Pack

A branded product formulation with pack size.

Eg: Panadol 50mg Tablet, pack of 20

CTPP Containered Trade Product Pack

A branded product formulation with specified pack size and container

Eg: Panadol 50mg Tablet, pack of 20, Blister Pack

In addition, the monthly distribution includes several combined views of these tables, the most significance of which – for SNAPP anyway – might be that containing all the unique available prescribing terms, generic and trade, with their associated concept identifiers and a flag to indicate whether the term is generic or trade.

Now – short of downloading grabbing the entire NZULM package and digesting copious amounts of additional documentation – how does one interact with this complex terminology without attempting to become an overnight expert? The answer offered here centres on the value proposition for terminology services – delegate most of that responsibility to specialist software and interact with a relatively simple, standards-based, API. In particular, the NZ Terminology Server (Terminz) built by Patients First Ltd.

For a simple introduction to Patients First Terminology Services a simple interactive test page is provided here:

1. Choose a Value Set
2. Select an operation
3. Enter a description (expand) or code (lookup and validate)
4. Click Submit Request…view results and the request URL (below)


For API access, assuming some knowledge of the basics of FHIR and the Terminology Service Section of the Specification, here are some basic URLs…

// Base URL

// request a Conformance Statement

// request definitions of all the available Code Systems

// request definitions of all the available Value Sets

The list of Value Sets contains an entry for each of the 7 NZMT Boxes tabulated above, plus an additional 3 that provide ‘generic only’, ‘trade only’ and ‘all’ concepts from the Prescribing Terms Table. These can be used at the target for requesting Expansions (e.g. for populating dropdowns controls on a user interface) or to Validate that a particular Code (concept identifier) belongs in a particular value set.

For example…

// [BASE ValueSet URL]

// Expansion filtered on all terms containing ‘cilazapril’
[BASE ValueSet URL] $expand?filter=cilazapril

// Validate that this code & code system combination belong to the Value Set
[BASE ValueSet URL] $validate-code?system=

Requests to Lookup codes operate across the NZMT Code System as a whole (i.e. the “Seven Boxes” of NZMT, which includes those contained in the Prescribing Terms Value Sets)…

// [BASE CodeSystem URL]

// Lookup this code in the passed code system and return any designations

Note that the last request also asks for the designations which, in addition to the code system, code and description, will return the following information…

  • NZULM Type…which of the Seven Boxes the code belongs to
  • Medicinal Product…The name of the generic substance linked to this concept
  • Is Base Substance…Whether the generic substance is the base substance
  • Ingredient…The active ingredient(s) in the generic substance


Happy SNAPPing!

About David Hay
I'm an independent contractor working with a number of Organizations in the health IT space. I'm an HL7 Fellow, Chair Emeritus of HL7 New Zealand and a co-chair of the FHIR Management Group. I have a keen interest in health IT, especially health interoperability with HL7 and the FHIR standard. I'm the author of a FHIR training and design tool - clinFHIR - which is sponsored by InterSystems Ltd.

2 Responses to Supporting SNAPP: Accessing New Zealand Medicines Terminologies With FHIR Terminology Services

  1. Nice PJ – happy snapping exactly – see you at and #snapp2016

  2. Peter Jordan says:

    I’ve just implemented a change to the name of one of the properties that can be requested in the NZMT Code $lookup operation. I realized that ‘designations’ relates to various terms/descriptions, so I’ve renamed it to ‘substance’ which, I hope, more accurately describes what’s returned (generic substance & ingredient).

Leave a Reply

%d bloggers like this: