---
title: "Map a species file's columns to Darwin Core terms"
method: POST
path: "/dwc/map"
---

# Map a species file's columns to Darwin Core terms

`POST /dwc/map`

## Request

- Base URL: `https://passage-data.com/api/v1`
- URL: `https://passage-data.com/api/v1/dwc/map`
- Auth: one of:
  - none
  - HTTP bearer
  - API key in header `x-api-key`

For each column of an occurrence or checklist file: the Darwin Core term, the rule that decided it (header_exact, header_token, header_packed, header_grid) and the alias that matched, or a coded `refused` block saying why it is unmapped. Also names the terms GBIF requires of an occurrence or checklist dataset that no column carries. The header rules of our file-to-archive converter; values are not checked here, and each mapped column names the check its values must still pass.

## Request body

- object
  - `columns` string[], required: The file's header names, in order, exactly as written.
  - `sample_rows` object[]: Optional data rows, each an array aligned with columns or an object keyed by header. A column blank in every row is skipped as the converter skips it; a column of distinct codes is named an identifier.

## Response `200`

One entry per column, the GBIF-required terms held and missing, and any ties to settle

- DwcMap
  - `rules` object
  - `scope` string
  - `columns` DwcColumn[]
    - `header` string
    - `status` 'mapped' | 'refused' | 'empty' | 'unmapped'
    - `term` string, nullable
    - `terms` string[]
    - `rule` 'header_exact' | 'header_token' | 'header_packed' | 'header_grid'
    - `evidence` object
      - `alias` string
      - `alias_rank` integer, nullable
      - `alias_origin` 'standard' | 'ours' | 'learned' | 'wikidata' | 'null', nullable
      - `table` string
      - `also_nominated` string[]
    - `values_check` object
      - `check` string
      - `run_here` boolean
      - `says` string
    - `named` string
    - `refused` object
      - `code` string
      - `says` string
  - `summary` object
  - `questions` object[]
  - `required` object
    - `occurrence` object
    - `checklist` object
  - `refused` object

## Other responses

- `400`: columns.missing, columns.malformed, columns.too_many, sample_rows.malformed, sample_rows.too_large, body.malformed
- `413`: body.too_large

---

[API](https://skmtc.dev/passage-data/apis/passage-data-cited-environmental-limits.md) · [All operations](https://skmtc.dev/passage-data/apis/passage-data-cited-environmental-limits/llms.txt) · [OpenAPI document](https://skmtc.dev/passage-data/apis/passage-data-cited-environmental-limits/revisions/ba066708bf53?raw)