# Filtering

**Dataloy REST API** uses a generic search/filtering functionality. In general, **all resources** supports filtering on **all properties** of that resource and linked resources (for exceptions, see [Limitations](#limitations)).

## **Syntax**

The filter query parameter has the following format: 

| `<Base URL>/<Resource>?filter=<json property>(OPERATOR)<value>` |
| --------------------------------------------------------------- |

Example that will return currency information for USD:

| `localhost/ws/rest/Currency?filter=currencyCode(EQ)USD` |
| ------------------------------------------------------- |

### Syntax Breakdown  \&#xNAN;**\<Base URL>**

For more information see [Getting Started with Dataloy REST API](https://api.dataloy.com/api-release-8.10/dataloy-rest-api/getting-started)\
&#x20;

**\<Resource>**&#x20;

Can be any of the [Resources](https://api.dataloy.com/api-release-8.10/dataloy-rest-api/data-model) available in the Dataloy API.

**\<json property>**&#x20;

Can be any json **property** of the [resource](https://api.dataloy.com/api-release-8.10/dataloy-rest-api/data-model) (for exceptions, see [Limitations](#limitations)).\ <br>

## **\<OPERATOR>**&#x20;

The operator is always:

* surrounded by parenthesis
* is always upper case

### **List of Operators**

<table data-full-width="true"><thead><tr><th>Operator</th><th>Description</th><th>API Version</th><th>Example</th></tr></thead><tbody><tr><td>(EQ)</td><td>Equals Exact Value, <em>case sensitive</em></td><td></td><td>Get a Document with document number 2707374: <strong>Document?filter=documentNo(EQ)2707374</strong></td></tr><tr><td>(NE)</td><td>Not Equal</td><td></td><td>Get all Documents not in company 1000: <strong>Document?filter=company.companyCode(NE)1000</strong></td></tr><tr><td>(GT)</td><td><p>Greater Than</p><p><em>ONLY numeric and date values</em></p></td><td></td><td>Get all Voyages modified since 2014-01-01 00:00:00, not including 2014-01-01 00:00:00: <strong>Voyage?filter=modifiedDate(GT)2014-01-01T00:00:00</strong></td></tr><tr><td>(GTE)</td><td><p>Greater Than or Equal</p><p><em>ONLY numeric and date values</em></p></td><td></td><td>Get all Voyages modified since 2014-01-01 00:00:00, including 2014-01-01 00:00:00: <strong>Voyage?filter=modifiedDate(GTE)2014-01-01T00:00:00</strong></td></tr><tr><td>(LT)</td><td><p>Lesser Than</p><p><em>ONLY numeric and date values</em></p></td><td></td><td>Get all Documents that has document amount less than 100000: <strong>Document?filter=documentAmount(LT)100000</strong></td></tr><tr><td>(LTE)</td><td><p>Lesser Than or Equal</p><p><em>ONLY numeric and date values</em></p></td><td></td><td>Get all Documents that has document amount less than 100000, including 100000: <strong>Document?filter=documentAmount(LT)100000</strong></td></tr><tr><td>(IN)</td><td>Equals One of the Elements in a Given List</td><td></td><td>Get all Documents that are ready for posting and has status type INI, INO, CRI or CRO: <strong>Document?filter=invoicingStatus.statusTypeCode(EQ)RFP&#x26;filter=invoicingStatus.statusTypeCode(IN)(INI,INO,CRI,CRO)</strong></td></tr><tr><td>(NULL)</td><td>Filter for NULL values</td><td>2.10</td><td>Get all Documents without business partner: <strong>Document?filter=businessPartner(NULL)</strong></td></tr><tr><td>(NOTNULL)</td><td>Filter for NOT NULL values</td><td>2.10</td><td>Get all Voyages with vessel: <strong>Voyage?filter=vessel(NOTNULL)</strong></td></tr><tr><td>(LK)</td><td>Like operator</td><td>3.3</td><td>Get all BunkerOrder with externalReferenceNo containing the string "test" case sensitive: <strong>BunkerOrder?filter=externalReferenceNo(LK)test</strong></td></tr><tr><td>(LKIC)</td><td>Like ignore case operator</td><td>3.3</td><td>Get all BunkerOrder with externalReferenceNo containing the string "test" case insensitive<strong>:</strong> BunkerOrder?filter=externalReferenceNo(LKIC)test</td></tr><tr><td>(NLK)</td><td>Not like </td><td>8.5</td><td>Get all BunkerOrder with externalReferenceNo not containing the string "test" case sensitive: <strong>BunkerOrder?filter=externalReferenceNo(NLK)test</strong></td></tr><tr><td>(NLKIC)</td><td>Not like ignore case</td><td>8.5</td><td>Get all BunkerOrder with externalReferenceNo not containing the string "test" case insensitive: <strong>BunkerOrder?filter=externalReferenceNo(NLK)test</strong></td></tr></tbody></table>

### **\<value>**

* **Numeric Values** are straight forward. Can be integers or decimal numbers using a dot as decimal point. <br>
* **Dates** must be specified in the format: **yyyy-MM-ddTHH:mm:ss**
* **Strings** *can* be surrounded by double quotes, but it is generally not necessary. Even if the string has spaces.
* **Boolean** must be specified with 0 for false and 1 for tru&#x65;**.**

## **Combining Filters**

The filter URL parameter can be added multiple times to filter on multiple properties in one request. To do so, add a new filter parameter to the end of the URL

### **Syntax for Combining Filters**

| `<Base URL>/<Resource>?filter=<json property>(OPERATOR)<value>&filter=<json property 2>(OPERATOR)<value>` |
| --------------------------------------------------------------------------------------------------------- |

Example:

| `<Base URL>/Document?filter=invoicingStatus.statusTypeCode(EQ)RFP&filter=invoicingStatus.statusTypeCode(IN)(INI,INO,CRI,CRO)` `Invoices ready to be transferred to accounting will be returned.` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

### **Properties for Sub Objects**

Filters can be used for sub objects by using a "dot path". Example of a sub object is commodity on Cargo:

```
Part of the Cargo resource as an example:
  
{
    "cargoReference": 12345,
    "freight": 20000,
    "cargoQuantity":100000,
    "commodity": {
            "commodityName": "Steel",
            "commodityCode": "10000",
            "key": 1069734,
            "self": "http://localhost:8080/ws/rest/Commodity/1069734"
    }
}
```

To search for cargoes with commodity steel:

| `<Base URL>/Cargo?filter=commodity.commodityCode(EQ)10000` |
| ---------------------------------------------------------- |

### **Limitations**

The following properties are currently not possible for filtering:

* self
* remarks

A few other properties are unsupported, these are documented for each resource.

## **Examples**

**Cargo**

Get Cargo with freight more than 1000000 and freightCurrency USD or EUR:

| `/Cargo?filter=freight(GT)1000000&filter=freightCurrency.currencyCode(IN)USD,EUR` |
| --------------------------------------------------------------------------------- |

**Document**

Get Documents with documentType "INV" and invoicingStatus "PEN"

| `/Document?filter=documentType.documentType(EQ)INV&filter=invoicingStatus.statusTypeCode(EQ)PEN` |
| ------------------------------------------------------------------------------------------------ |

**Voyage**&#x20;

Get Voyages for the vessel with vessel code ABRA

| `/Voyage?filter=voyageHeader.vesselCode.vesselCode(EQ)ABRA` |
| ----------------------------------------------------------- |

Get Voyage with reference number VES100

| `/Voyage?filter=voyageHeader.referenceNo(EQ)VES100` |
| --------------------------------------------------- |

Get Voyage with start date > 01.01.2016 and operator is user with userCode "BAK"

| `/Voyage?filter=voyageHeader.voyageStartDate(GT)2016-01-01T00:00:00&voyageHeader.operator.userCode(EQ)BAK` |
| ---------------------------------------------------------------------------------------------------------- |

Get Voyages that are operational for vessel ABRA

| `/Voyage?filter=voyageHeader.voyageStatus.statusTypeCode(EQ)OPR&filter=voyageHeader.vesselCode.vesselCode(EQ)ABRA` |
| ------------------------------------------------------------------------------------------------------------------ |

Get all Voyages that has Oslo as Load Port in 2015

| `/Voyage?filter=portCalls.reasonForCall.reasonForCall(EQ)L&filter=portCalls.port.portName(EQ)OSLO&filter=voyageHeader.voyageStartYear(EQ)2015` |
| ---------------------------------------------------------------------------------------------------------------------------------------------- |