Matches
- Mike Cochrane
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.
Id, ScientificName 1, Lichen 2, Parmelia
Parameters
| inputformat | Specifies the format of the input
|
|---|---|
| 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.
<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 |
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 |
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"