The matches endpoint provides a way of submitting lists of names to the service and retrieving a list of potential matches.

Batch matching is an off-line process that can take some time to complete for files containing a large number of names.

Email notifications are used to inform the submitter of progress and to provide a download link to the completed results.

Methods

/matches/{matchId}

Downloads the results of the batch matching.

/matches/batch?email={email}

POST

Submits a list of names in the following comma separated format:

Id, ScientificName
x, y

Note: The header row is required.

E.g.

Example Matching File

Id, ScientificName
1, Lichen
2, Parmelia

Parameters

inputformat

Specifies the format of the input

standard
dwcarchive

email

The email address that will be notified when processing is complete

Post Body

The DwC archive binary file

Submitting Darwin Core Archive Files

Darwin Core Archives are a standard for packaging self-contained datasets of species concurrence or check list data.

Methods

/matches/batch?inputformat=dwcarchive&email={email}

POST

Overview

Once a valid Darwin Core Archive has been submitted the batch matching process will parse the metadata of the archive to locate data matching the http://rs.tdwg.org/dwc/terms/scientificName term identifier. Any data that is identified as a scientific name is then matched against NZOR data and the closest matches are added to a new file that is inserted into the archive as a MeasurementOrFact extension..

The new file is called nzor-result.txt.

Metadata Extension

  <extension linesTerminatedBy="\t" fieldsTerminatedBy="\n" fieldsEnclosedBy="" ignoreHeaderLines="1" rowType="http://rs.tdwg.org/dwc/terms/MeasurementOrFact" encoding="UTF-8">
    <files>
      <location>nzor-result.txt</location>
    </files>
    <coreid index="0" />
    <field term="http://rs.tdwg.org/dwc/terms/occurrenceID" />
    <field index="1" term="http://rs.tdwg.org/dwc/terms/measurementType" />
    <field index="2" term="http://rs.tdwg.org/dwc/terms/measurementValue" />
    <field index="3" term="http://rs.tdwg.org/dwc/terms/measurementAccuracy" />
    <field index="4" term="http://rs.tdwg.org/dwc/terms/measurementMethod" />
    <field index="5" term="http://rs.tdwg.org/dwc/terms/measurementDeterminedBy" />
    <field index="6" term="http://rs.tdwg.org/dwc/terms/measurementRemarks" />
  </extension>

Columns

Column	Description
occurrenceID	The Id used in the data file that contained the scientific name record.
measurementType	the constant `scientificName`
measurementValue	The NZOR Identifier for the closest match or the constant `No Match` if there was not match for the submitted name.
measurementAccuracy	Description of how many other names were possible matches.
measurementMethod	The constant `String Matching`
measurementDeterminedBy	The constant `NZOR`
measurementRemarks	The full name of the closest matching NZOR record.

Records where there is a match as list first and then followed by the records that were not matched.

Example Post Command Using CURL

curl -X POST --data-binary @"path-to-archive" "http://data.nzor.org.nz/matches/batch?inputformat=dwcarchive&email=email-address"