---
title: "Run queries against DigitalNZ metadata search service."
method: GET
path: "/records.{format}"
tags: ["API calls"]
---

# Run queries against DigitalNZ metadata search service.

`GET /records.{format}`

This is the main search endpoint allowing queries against the records database.

## Path parameters

- `format` 'json' | 'xml', required

## Query parameters

- `text` string
- `and[category][]` 'Newspapers' | 'Images' | 'Books' | 'Articles' | 'Journals' | 'Archives' | 'Audio' | 'Other' | 'Manuscripts' | 'Reference sources' | 'Research papers' | 'Videos' | 'Music Score' | 'Groups' | 'Data' | 'Websites' | 'Sets'
- `and[content_partner][]` string
- `and[primary_collection][]` string
- `and[collection][]` string
- `and[usage][]` 'Share' | 'Modify' | 'Use commercially' | 'All rights reserved' | 'Unknown'
- `and[subject][]` string
- `and[dc_type][]` string
- `and[format][]` string
- `and[placename][]` string
- `and[creator][]` string
- `and[title][]` string
- `and[date]` string
- `and[year]` string
- `and[decade]` string
- `and[century]` string
- `without[{filter_field}]` string
- `and[or][{filter_field}][]` string
- `and[is_commercial_use]` boolean
- `and[has_large_thumbnail_url]` 'Y'
- `and[has_lat_lng]` true | false
- `geo_bbox` string
- `fields` string
- `sort` 'syndication_date' | 'date'
- `direction` 'asc' | 'desc'
- `page` integer
- `per_page` integer
- `facets` string[]
- `facets_page` integer
- `facets_per_page` integer
- `exclude_filters_from_facets` boolean

## Headers

- `Authentication-Token` string

## Response `200`

search results matching criteria

- object
  - `result_count` integer — Total number of matching search results.
  - `page` integer — Current page.
  - `per_page` integer — Requested amount of records shown per page of results.
  - `request_url` string — The URL of current page of results.
  - `records` Record[]
    - `id` integer — All records have a unique identifier used within the DigitalNZ system.
    - `created_at` string, date-time — The date the record was initially harvested into DigitalNZ.
    - `updated_at` string, date-time — The date the record was last updated/re-harvested into DigitalNZ.
    - `title` string — Title of the record. All records should have a title.
    - `description` string — Description of the record. Most records have a description.
    - `content_partner` string[] — Name of the organisation(s), institution(s), or individual(s) making content available through DigitalNZ. This metadata will be present on all records and is usually the name of the organisation that has agreed to the DigitalNZ Metadata Contribution Terms.
    - `display_content_partner` string — The main Content Partner, for cases when there are more than one. This metadata will be present on all records.
    - `display_collection` string — The single main collection or website that the item belongs to. This metadata will be present on all records.
    - `primary_collection` string[] — In most cases this is the same as *display_collection*, but will occasionally a second value.
    - `collection` string[] — In addition to the top level *"display_collection"* above, this field can also contain sub-collections or groupings within the main collection.
    - `collection_title` string[] — For historic reasons this is a duplicate of the previous field ("collection").
    - `category` string[] — There will always be at least 1 human-readable category label in this field.
    - `creator` string[] — The name's of the people, organisations, institutions, services etc. who created the content (eg. the photographer, artist, writer or author).
    - `subject` string[] — Keywords about the content.
    - `dc_identifier` string[] — Identifiers relating to the content from the content partner's system.
    - `date` string[] — Date information associated with this record (e.g. 1996-01-01T00:00:00.000Z). This field may be empty.
    - `display_date` string — Where provided, this field contains a human readable version of the date information.
    - `landing_url` string — This field will always contain a URL of the item on the content partner's website. *Note:* Please use the source_url when providing HTML links.
    - `source_url` string — This URL will always be present and provides a redirect to the landing_url. This link should be used as the main click-through to the content. Passing users through this link allows DNZ to count the number of click-throughs, as well as trigger link-checking activities that help clean up stale links in DigitalNZ.
    - `thumbnail_url` string — URL for a thumbnail image of the content. The size varies depending on what is available but we aim for a width of 250px. This field is mostly populated on records with a 'category' of 'Images', but is also sometimes found on others (eg. "Videos").
    - `large_thumbnail_url` string — URL for a larger thumbnail image with a width of up to 800px. NOTE - the API Terms do not extend rights to the use of images accessable throught the *large_thumbnail_url* field.
    - `usage` string[] — This field is always present and contains human-understandable information about how the item may be used based on its copyright/license.
    - `copyright` string[] — A copyright statement applying to the object referenced by this record. This field may be empty.
    - `rights` string — Rights information. Can be a rights statement explaining the rights of the record or a link to a webpage with more detailed rights information.
    - `rights_url` string[] — An array of HTTP URLs resolving to a rights statement or terms of use information for the resource.
    - `locations` object[] — Geographical location information including latitude and longitude co-ordinates, text based location information, and details about where the location information comes from (eg. "Location provided by Museum of New Zealand Te Papa Tongarewa")
      - `lat` number
      - `lng` number
      - `placename` string
      - `comment` string — Describes who provided this location metadata.
  - `facets` object — Each field you request from the list of facetable fields will be returned as separate elements. Each of those will contain a sorted list of elements that are made up of a value (eg collection name, subject, date) and the number of results associated with that value.

## Other responses

- `400` — Incorrect field specified in the request.
- `403` — API Key (Authentication-Token) is invalid.

---

[API](https://skmtc.dev/swaggerhub/apis/digitalnz-api.md) · [All operations](https://skmtc.dev/swaggerhub/apis/digitalnz-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/swaggerhub/digitalnz-api/revisions/74a66ebbc850/schema)