Matches

Owned by Mike Cochrane
Last updated: Jun 26, 2015
2 min read

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
emailThe email address that will be notified when processing is complete
Post BodyThe 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

ColumnDescription
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"