Getting started

Find hidden NZ content Uncover amazing aerial photos, posters, newspapers, artwork, research papers and more. Use DigitalNZ to discover millions of NZ items from the digital stores of libraries, museums, archives, communities, and government.

How to Build

The generated SDK relies on Node Package Manager (NPM) being available to resolve dependencies. If you don't already have NPM installed, please go ahead and follow instructions to install NPM from here. The SDK also requires Node to be installed. If Node isn't already installed, please install it from here

NPM is installed by default when Node is installed

To check if node and npm have been successfully installed, write the following commands in command prompt:

• node --version
• npm -version

Now use npm to resolve all dependencies by running the following command in the root directory (of the SDK folder):

npm install

This will install all dependencies in the node_modules folder.

Once dependencies are resolved, you will need to move the folder DigitalNewzealandLib in to your node_modules folder.

How to Use

The following section explains how to use the library in a new project.

1. Open Project Folder

Open an IDE/Text Editor for JavaScript like Sublime Text. The basic workflow presented here is also applicable if you prefer using a different editor or IDE.

Click on File and select Open Folder.

Select the folder of your SDK and click on Select Folder to open it up in Sublime Text. The folder will become visible in the bar on the left.

2. Creating a Test File

Now right click on the folder name and select the New File option to create a new test file. Save it as index.js Now import the generated NodeJS library using the following lines of code:

var lib = require('lib');

Save changes.

3. Running The Test File

To run the index.js file, open up the command prompt and navigate to the Path where the SDK folder resides. Type the following command to run the file:

node index.js

How to Test

These tests use Mocha framework for testing, coupled with Chai for assertions. These dependencies need to be installed for tests to run. Tests can be run in a number of ways:

Method 1 (Run all tests)

1. Navigate to the root directory of the SDK folder from command prompt.
2. Type mocha --recursive to run all the tests.

Method 2 (Run all tests)

1. Navigate to the ../test/Controllers/ directory from command prompt.
2. Type mocha * to run all the tests.

Method 3 (Run specific controller's tests)

1. Navigate to the ../test/Controllers/ directory from command prompt.
2. Type mocha DigitalNewzealandController to run all the tests in that controller file.

To increase mocha's default timeout, you can change the TEST_TIMEOUT parameter's value in TestBootstrap.js.

Initialization

Authentication

In order to setup authentication in the API client, you need the following information.

| Parameter | Description | |-----------|-------------| | apiKey | Your API Key |

API client can be initialized as following:

const lib = require('lib');

// Configuration parameters and credentials
lib.Configuration.apiKey = "apiKey"; // Your API Key

Class Reference

List of Controllers

• SearchRecordController
• MetadataController

SearchRecordController

Get singleton instance

The singleton instance of the SearchRecordController class can be accessed from the API Client.

var controller = lib.SearchRecordController;

searchRecord

The Search Records API call returns a result set in response to a search query. The v3 Search Records API request parameters and response format differs significantly from the deprecated v1 & v2 Search Records API call.

function searchRecord(input, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | text | Required | TODO: Add a parameter description | | and | Optional | Restricts search to records matching all facet values. Example: "&and[content_partner][]=Kete+Horowhenua&and[category][]=Images" | | or | Optional | Restricts search to records matching any of the specified facet values. Example: "&or[category][]=Image&or[category][]=Videos"without | | without | Optional | Restricts search to records that don't match any of the facet values. Example: "&without[category][]=Newspapers" | | page | Optional DefaultValue | the page when iterating over a set of records. (Defaults to 1.) | | perPage | Optional DefaultValue | the number of records the user wishes returned up to a maximum of 100. (Defaults to 20.) | | facets | Optional | a list of facet fields to include in the output. See the note on facets below for more information. Example: "&facets=year,category" | | facetsPage | Optional DefaultValue | the facet page to iterate over a set of facets. . (Defaults to 1.) | | facetPerPage | Optional DefaultValue | the number of facets returned for every page. (Defaults to 10.) | | sort | Optional | the field upon which results are sorted. Defaults to relevance sorting. The sort field must be one of: "category", "content_partner", "date", "syndication_date". | | direction | Optional | the direction in which the results are sorted. Possible values: "desc", "asc". | | geoBbox | Optional | a geographic bounding box scoping a search to a geographic region. Order of latitude-longitude coordinates is north, west, south, east. For example, &geo_bbox=-41,174,-42,175 searches the Wellington region. |

Example Usage

    var input = [];
        input['text'] = 'text';
        input['and'] = 'and';
        input['or'] = 'or';
        input['without'] = 'without';
        input['page'] = 172;
        input['perPage'] = 172;
        input['facets'] = 'facets';
        input['facetsPage'] = 172;
        input['facetPerPage'] = 172;
        input['sort'] = 'sort';
        input['direction'] = 'direction';
        input['geoBbox'] = 172.001867402346;

    controller.searchRecord(input, function(error, response, context) {

    
    });

Back to List of Controllers

MetadataController

Get singleton instance

The singleton instance of the MetadataController class can be accessed from the API Client.

var controller = lib.MetadataController;

getMetadata

The Get Metadata API call returns the available metadata for a specific item. The Get Metadata v3 request parameters and response format differs significantly from the depreciated Get Metadata v1 & v2 API call.

function getMetadata(input, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | recordId | Required | Record IDs are identified in the metadata_url field of a results set. 23034653 is an example record ID. | | fields | Required | A comma separated list of fields or groups of fields to be returned for each record. Possible groups include 'default' and 'verbose'. If no value is specified, then the 'default' field group will be returned. |

Example Usage

    var input = [];
        input['recordId'] = record_id;
        input['fields'] = 'fields';

    controller.getMetadata(input, function(error, response, context) {

    
    });

Back to List of Controllers