Search Functionality and response objects

Filters

In all of the search endpoints it is possible to supply a json string to make a filtered search based on a set of supported filter fields. 

You can get all the valid fields by doing the following API call:

• GET /info/filter

 We currently support the following filter functions: 

• Equal filter
• Range filter
• Date filter

Equal filter

The 'filter' parameter accepts a list of key-value pairs which will be ANDed together.

For testing directly in the browser it is possible to supply the filters as a comma separated list in the format: "field1:value1,field2:value2".

For implementation purposes the calls support supplying the filters to be provided as a JSON array. Such as: 'filter':{"field1":"value1", "field2":"value2"}'.

Example

Search with the query 'bil' filtered on the county 'Vestfold' can be done by doing the following call:

• GET /company?querystring=bil&filters=county:vestfold

Search with the query 'bil' filtered on the county 'Vestfold' AND CompanyNameWords 'sentrum' can be done by doing the following call:

• GET /company?querystring=bil&filters=county:vestfold,CompanyNameWords:sentrum

Range filter

It is possible to do a range filter on numeric fields.

Example

For example, if you want to do a range filter on the query 'Markus' filtered on Housenumber from 1 to 2, you can do the following API call: 

• GET /person?querystring=markus&filters=houseNumber:1-2

Rangefilter på datofelt

All the datetime fields are defined in the format YYYY-MM-DD. Since the character '-' is used to specify a date we use an additional '-' to specify that it is a range filter query.

Example

For example, if you want to do a range query on 'bil' you can define a date filter by doing the following API call:

• GET /company?querystring=bil&filters=datefield:2015-02-01--2015-03-01

Advanced filters

By providing a valid JSON string in the filter parameter it is possible to supply the operators:

• AND
• OR

Example

Search for companies within counties Vestfold OR Bergen AND has key figures can be done by creating the the following filter object: 

• {
   "and": [
     {"or": [{"county":"bergen"},{"county":"vestfold"}]},
      {"hasKeyFigures":true}
   ]
  }

This may be used in an API call against the /company endpoint such as:

• GET /company?querystring=&filters={ "and": [ {"or": [{"county":"bergen"},{"county":"vestfold"}]}, {"hasKeyFigures":true} ] }

Facets (also known as Refiners, Navigators)

Facet queries returns aggregations on provided fields.

Return type description:

Examples:

This is how you retrieve facets 'PostalArea' and 'Region' for the query "rørlegger". The result of the following call will return aggregated counts of how many plumbers there are in each postal area and region in Norway:

• GET /person?querystring=rørlegger&facets=PostalArea,Region

This is how you retrieve facets 'LastName' and 'PostalArea' for the query "markus olsen". The result of the following call will return aggregated counts of how many people are named "markes olsen" in each postal area in Norway and how many has 'olsen' as their lastname:

• GET /person?querystring=markus olsen&facets=LastName,PostalArea

SortBy

The API supports sorting on multiple sortable fields with the typical sorting directions ascending or descending. 

Example:

Search for 'Markus Olsen' with a descending sort on Lastname looks like this:

• GET /person?querystring=markus olsen&sortby=LastName:DESC

Fields

With the 'fields' parameter you wan specify which fields you want to retrieve in order to minimize the returning payload. If this field is not specified all the default fields will be returned.

All the fields can be specified in the format 'object.property', however if it's not specified the service will translate them to valid fields.

For instance:

• GET /company?querystring=media&fields=id,name,companycode

Will be transformed to the following in the service: 

• GET /company?querystring=media&fields=company.id,company.name,company.companycode

Examples

To return only Id, Name and CompanyCode (VAT-number) on companies the API call can be specified like:

• GET /company?querystring=rørlegger&fields=id,name,companycode

To return only Id and Name on companies the API call be specified like:

• GET /company?querystring=rørlegger&fields=id,name

To return all the fields on companies the API call be specified like:

• GET /unit?querystring=rørlegger&fields=*