# 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](/api-release-8.25/dataloy-rest-api/getting-started.md)\
&#x20;

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

Can be any of the [Resources](/api-release-8.25/dataloy-rest-api/data-model.md) available in the Dataloy API.

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

Can be any json **property** of the [resource](/api-release-8.25/dataloy-rest-api/data-model.md) (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><tr><td>(NOTIN)</td><td>Is not one of the elements in a given list</td><td>8.13</td><td>Get all Documents that are ready for posting and has status type other than CRI or CRO: Document?filter=invoicingStatus.statusTypeCode(EQ)RFP&#x26;filter=invoicingStatus.statusTypeCode(NOTIN)(CRI,CRO)</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` |
| ---------------------------------------------------------------------------------------------------------------------------------------------- |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api.dataloy.com/api-release-8.25/dataloy-rest-api/filtering.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.