---
title: "Build a Darwin Core archive from a species file or a list of names"
method: POST
path: "/dwc/archive"
---

# Build a Darwin Core archive from a species file or a list of names

`POST /dwc/archive`

## Request

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

A file this tool reads, sent or fetched from the address given, is read as one dropped on our website: what the read finds (column headings, the shape of its rows, the terms they became, refusal codes) is kept so the reader learns, never the file or its values. Names and contacts are dropped or replaced by a code, and protected species' locations are made coarser. A species occurrence or checklist file (CSV, TSV, Excel, a zipped shapefile, ...) given as `file_url` (a public https address the door fetches) or `content_base64`, or a list of scientific names (`species`, a checklist), becomes a Darwin Core archive for GBIF: occurrence.txt or taxon.txt, meta.xml and eml.xml, built by the converter behind map_to_darwin_core, which maps every column and checks every value. The zip comes back whole in `archive.base64`, with each thing the converter would not guess coded in `could_not_read` (the same lines ship inside the archive as passage-data-exceptions.csv and .json). GBIF indexes an archive only with a title, an abstract, a licence and a creator and a contact (given name, surname, organisation, email): give them in `metadata`; nothing is filled in. `chapman_category` (1-4, the data holder's own Chapman 2020 category) coarsens the coordinates of species a conservation register lists. `columns` names the column for a term where your user decided; the values are still checked. With `columns_confirmed_by_user: true` (your user confirmed every entry) each confirmed column's words and term, never a value, are also read as a label to teach the converter, said in `learned`. A large file takes up to a minute.

## Request body

- object
  - `file_url` string: A public https address of the file (at most 10 MB). Not with content_base64 or species.
  - `content_base64` string: The file's bytes as base64 (at most 10 MB decoded). Not with file_url or species.
  - `filename` string: The file's name with its extension (survey.xlsx, sites.zip); taken from file_url when omitted.
  - `species` string[]: Instead of a file: scientific names, one an entry, for a checklist archive.
  - `core` 'occurrence' | 'checklist': occurrence (the default for a file) or checklist (the default for species).
  - `metadata` object
    - `title` string
    - `abstract` string
    - `license` 'CC0-1.0' | 'CC-BY-4.0' | 'CC-BY-NC-4.0'
    - `creator` Party: GBIF needs given, sur, organization and email.
      - `given` string
      - `sur` string
      - `organization` string
      - `email` string
      - `position` string
      - `country` string
      - `url` string
    - `contact` Party: GBIF needs given, sur, organization and email.
      - `given` string
      - `sur` string
      - `organization` string
      - `email` string
      - `position` string
      - `country` string
      - `url` string
  - `chapman_category` integer: Your sensitivity category under Chapman 2020: listed species' coordinates generalised to its grid, said in dataGeneralizations.
  - `columns` object: {Darwin Core term: column} where your user decided. A choice, not an order: the values are still checked.
  - `columns_confirmed_by_user` boolean: true only when your user confirmed every entry of `columns`: their words and terms are then kept to teach the converter.

## Response `200`

The archive (base64) and its receipt, what could not be read, notices

- DwcArchive
  - `archive` object
    - `filename` string
    - `bytes` integer
    - `sha256` string
    - `core` string
    - `records` integer
    - `rows_in` integer
    - `rows_lost` integer
    - `rows_refused` integer
    - `terms` string[]
    - `extensions` string[]
    - `members` object[]
      - `name` string
      - `bytes` integer
    - `publishable` object
      - `ok` boolean
      - `missing` string[]
      - `says` string
    - `generalised` object, nullable
    - `inline` boolean
    - `base64` string
  - `could_not_read` object
    - `n` integer, nullable
    - `vocabulary` string
    - `items` object[]
      - `code` string
      - `scope` string
      - `about` string
      - `n_rows` union
        - integer
        - string
      - `status` string
      - `what_it_means` string
      - `what_we_saw` string
  - `notices` string[]
  - `says` string
  - `kept` string
  - `engine` object
    - `upload_id` string
    - `seconds` number
  - `refused` object

## Other responses

- `400`: source.missing, source.ambiguous, file.ambiguous, file.malformed, file.url_refused, filename.malformed, species.malformed, species.too_many, species.not_occurrences, core.malformed, chapman_category.malformed, metadata.malformed, license.unrecognised, columns.malformed, columns.term_unknown, body.malformed
- `402`: archive.priced: past the free conversion allowance (about 50,000 records)
- `413`: file.too_large, body.too_large
- `422`: archive.not_built: the converter's own reason (no species name reached the archive, ...); file.unreachable: the file_url did not answer with the file
- `429`: engine.busy: the converter's per-caller budget
- `503`: engine.unreachable, engine.timeout: the converter did not answer

---

[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)