Skip to content

Search API records english version

Jump to bottom
nilsw-ra edited this page Jun 29, 2023 · 5 revisions

Svensk version

The main method of the Search API, for searching and filtering.

https://data.riksarkivet.se/api/records?...

Parameters

The records method uses query parameters for search conditions, filtering, pagination and sorting. Parameter default values are highlighted in bold.

Search condition

The condition parameters may be combined.

Parameter Use Example
text General free text search https://data.riksarkivet.se/api/records?text=Nobel
name Free text search on name https://data.riksarkivet.se/api/records?name=Nobel
place Free text search on referenced place name https://data.riksarkivet.se/api/records?place=Stockholm

Sorting

Parameter Use Example
relevance Relevance sort (default) https://data.riksarkivet.se/api/records?text=Nobel&sort=relevance
alphaAsc Alphabetic A-Ö, i första hand på namn/titel https://data.riksarkivet.se/api/records?text=Nobel&sort=alphaAsc
alphaDesc Alphabetic Ö-A, i första hand på namn/titel https://data.riksarkivet.se/api/records?text=Nobel&sort=alphaDesc
timeAsc Time order, oldest first https://data.riksarkivet.se/api/records?text=Nobel&sort=timeAsc
timeDesc Time order, newest first https://data.riksarkivet.se/api/records?text=Nobel&sort=timeDesc

Pagination

Parameter Use Example
offset Start position in the total search result, default value 0 https://data.riksarkivet.se/api/records?text=Nobel&offset=100
max Max number of hits in the result list, default value 100 https://data.riksarkivet.se/api/records?text=Nobel&max=20

Filtering

Parameter Use Example
year_min Earliest year https://data.riksarkivet.se/api/records?text=Nobel&year_min=1900
year_max Latest year https://data.riksarkivet.se/api/records?text=Nobel&year_max=1920
facet Faceting of the search result, specify one of more filters using facet name:value[;facet name:value]... https://data.riksarkivet.se/api/records?text=stockholm&facet=ObjectType:Record;Type:Volume

Available facets for filtering

General

Facet name Description Values Example
ObjectType Object type, information category
  • RecordSet (archive record, collection)
  • Record (arkiv record, single)
  • Agent (authority)
  • Topography
 https://data.riksarkivet.se/api/records?text=Vång&facet=ObjectType:Topography
Place Place, localization Place name, can be hierarchical e.g. Sverige/Stockholms län/Stockholms kommun https://data.riksarkivet.se/api/records?text=stockholm&facet=Place:Sverige/Blekinge%20län/Karlshamns%20kommun/Asarums%20församling

The other facets are specific (or have specific value sets) for object types.

Archive records, RecordSet

Facet name Description Values Example
Type Record type
  • Fonds
  • Series
 https://data.riksarkivet.se/api/records?text=stockholm&facet=ObjectType:RecordSet;Type:Series

Archive records, Record

Facet name Description Values Example
Type Record type
  • Volume
  • Dossier
  • Photography
  • MapDrawing
  • MotionPicture
  • SoundRecording
  • DigitalImage
  • DigitalFile
  • DigitalMedium
  • DigitalImageCopy
  • Microfilm
  • MicrofilmCopy
  • SearchUtility (Search aid)
  • Component
 https://data.riksarkivet.se/api/records?text=stockholm&facet=ObjectType:Record;Type:MapDrawing

Archive record, RecordSet and Record

Facet name Description Values Example
ArchivalInstitution Archival institution (holding archive) Name of archival institution, e.g. Riksarkivet i Stockholm/Täby, Arkivenheten, Region Värmland https://data.riksarkivet.se/api/records?text=stockholm&facet=ObjectType:Record;ArchivalInstitution:Riksarkivet%20i%20Täby,%20Krigsarkivet
Provenance Authority category for provenance
  • GovernmentAuthority
  • MunicipalAuthority
  • Company
  • Association
  • Village
  • Homestead
  • Person (Family)
  • Other
  • Unspecified

Authorities

Facet name Description Values Example
Type Authority type
  • FormerGovernmentAuthority
  • GovernmentAuthority
  • ArchivalInstitution
  • FormerGovernmentAuthorityUnit (Unit within former authority)
  • GovernmentAuthorityUnit (Unit within former authority)
  • Depot
  • FormerOrganization
  • Organization
  • FormerOrganizationUnit
  • OrganizationUnit
    Person (Person)
  • UnidentifiedPerson
  • Family
  • SystemAuthority
  • Congress (Kongress)
  • FormerPublicContractor
  • PublicContractor
 https://data.riksarkivet.se/api/records?text=stockholm&facet=ObjectType:Agent;Type:Family

Topographies

Facet name Description Values Example
Type Topography type
  • Country
  • County
  • Bailiwick
  • Parish
  • Municipality
  • Diocese
  • Decanate
  • Pastorship
  • CourtOfAppeal
  • Jurisdiction
  • Hundred
  • DistrictCourt
  • MilitaryDivision
  • Province
  • AncientProvince (Folkland, old swedish division)
  • SettlementUnit
    ParishPart
 https://data.riksarkivet.se/api/records?text=stockholm&facet=ObjectType:Topography;Type:Parish

Search result

The search result is a JSON object with four sections.

Header

The Header sektionen is four elements directly in the root level of the result object:

Element Description
totalHits Total number of hits in the search
hits Number of hits on this page of the search
offset Pagination position, specified as the number of result items, not page number, e.g. hits=100, offset=200 means that the page result lists item 201-300 in the total result 
{
   "totalHits": 1912668,
   "hits": 100,
   "offset": 0,
   ...

Facets

The filtering facets are found in an array under the facets element.

   ...
   "facets": [
      ...
   ],
   ...

Each facet is an object with these elements:

Element Description
name Facet name:
  • ObjectType
  • Type
  • ArchivalInstitution
  • Provenance
  • Place
values Array of facet values

Facet value

Object with these elements:

Element Description
value Value (text)
hits Number of hits with this value in the facet field (heltal)
url Search API URL to repeat the current search, filtered on the facet value at hand.
E.g. https://data.riksarkivet.se/api/records?text=stockholm&facet=ObjectType%3ARecord%3BType%3AVolume&offset=0&max=100&sort=relevance
NB! URL-encoding
subFacets (not always present) List of sub-facets, i.e. filtering specific to the superior facet value, sub-facets have the same structure as facet values 
   "facets": [
      ...,
      {
         "name": "Provenance",
         "values": [
            {
               "value": "GovernmentAuthority",
               "hits": 1474491,
               "url": "https://data.riksarkivet.se/api/records?text=stockholm&facet=Provenance%3AGovernmentAuthority&offset=0&max=100&sort=relevance"
            },
            {
               "value": "Other",
               "hits": 127972,
               "url": "https://data.riksarkivet.se/api/records?text=stockholm&facet=Provenance%3AOther&offset=0&max=100&sort=relevance"
            },
            ...
         ]
       },
       ...
   ]

Result list

The actual result list is an array under the element items.

Result item

JSON object with these elements:

Element Description
id Persistent id (text), differenr format for different object types

  • Archive record - Base 62-encoded UUID, e.g. 63zworBzgX0hO3dzp9XkbC
  • Authorities - Base 62-encoded UUID, e.g. iptBxAgXqn6ULG2G9x3yT1
  • Topographies - database id, numeric, up to 9 figures, e.g. 569
objectType Object type

  • RecordSet - arkive record, collection
  • Record - archive record, single
  • Agent - authority
  • Topography - place
type Detailed type, within each object type (text)
caption Name/title (text)
metadata JSON object with metadata for the item, exact elements depends on object type
_links JSON object with links to representations of the item

  • self - the item's linked data URI
  • html - web page for the item
  • rdf/xml - RDF, serialized as RDF/XML
  • json-ld - RDF, serialized as JSON-LD
  • ead/ra - EAD-XML, National Archives EAD 2002 schema (archive records only)
  • ead/ape - EAD-XML, Archives Portal Europes EAD 2002 schema (archive records only)
  • image - URI to IIIF manifest (if available)

Metadata

Archive records

Element Description
referenceCode Reference code, human readable archive identity (text)
hierarchy The archive record's hierarchy, fonds/sub-fonds/series/sub-series/..., array of JSON objects

  • uri - linked data URI of the archive record
  • caption - name/title
  • date - dating
provenance Provenance, array of JSON objects, structure same as for hierarchy
archivalInstitution Archival instiution, holding archive, array of JSON objects, struktur same as for hierarchy
date Dating (text), NB! the dates are not normalized, there can be other text than just year numbers, e.g. "1951 - November 1. Stockholm - Södermanland 1."
note Note (text) 
   ...
   "metadata": {
      "referenceCode": "SE/RA/1209/01/1/30/5578",
      "hierarchy": [
         {
            "caption": "Finansdepartementet/Budgetdepartementet",
            "uri": "http://data.riksarkivet.se/archive/dYINeBUQrH6d0002H087k3"
         },
         {
            "caption": "Finansdepartementet. Huvudarkivet",
            "uri": "http://data.riksarkivet.se/archive/doINeBUQrH6d0002H087k3"
         },
         {
            "caption": "Huvudarkiv",
            "uri": "http://data.riksarkivet.se/archive/2SRdhLyUkI1PY4mZNXY1D0"
         },
         {
            "caption": "EIa Konseljakter",
            "uri": "http://data.riksarkivet.se/archive/1ziJGUpj9YBLoOBQauZhP7"
         }
      ],
      "provenance": [
         {
            "caption": "Finansdepartementet",
            "uri": "http://data.riksarkivet.se/agent/VlaTA8hDrH646m3GjpvwY3"
            "date": "1840 - "
         }
      ],
      "archivalInstitution": [
         {
            "caption": "Riksarkivet i Stockholm/Täby",
            "uri": "http://data.riksarkivet.se/agent/nyzaW7QeDCHdbK0a2Umzd9"
         }
      ],
      "date": "1951 - November 1. Stockholm - Södermanland 1."
   },
   ...

Authorities

Element Beskrivning
referenceCode Reference code, human readable identity (text)
date Dating (text), NB! the dates are not normalized, there can be other text than just year numbers

Topographies

Element Description
referenceCode Reference code, human readable identity (text)
partOf Closest superior topographies, array of JSON objects, structure same as for archive records hierarchy
date Dating (text), NB! the dates are not normalized, there can be other text than just year numbers

Links

Links for the entire search result are collected in a JSON object under the element _links.

Element Description
self URL to the current search
next URL to the next result page (new offset = offset + max)
previous URL to the previous result page (new offset = offset - max) 
   _links": {
      "self": "https://data.riksarkivet.se/api/records?text=stockholm&facet=ObjectType:Topography&offset=100&max=100",
      "next": "https://data.riksarkivet.se/api/records?text=stockholm&facet=ObjectType:Topography&offset=200&max=100",
      "previous": "https://data.riksarkivet.se/api/records?text=stockholm&facet=ObjectType:Topography&offset=0&max=100"
   }

Riksarkivet

Clone this wiki locally