Skip to main content

Querying

The Harlyy API allows for basic & advanced queries for data retrieval.

Basic Querying​

All list retrieval endpoints can use the Query object in order to sort, filter & paginate results.

The Query Object​

Schema Query not found in OpenAPI spec.

Usage​

Example Query
GET https://api.harlyy.com/v1/businesses/bus_668418dc2ef437a91fbbfe0b/locations?
  page=0&
  pageSize=20&
  sorts={"field":"createdAt","order":"desc"}&
  filters={"field":"name","type":"eq","value":"London"}&
  filters={"field":"createdAt","type":"gte","value":1738935854165}

Advanced Querying​

Some endpoints may also have additional options, which can allow for more advanced querying. Such as the GET /v2/businesses/:business/reviews endpoint, which can be filtered by to return review that have a specific ReviewCategory assigned to them.

These options are specified in each endpoint's documentation.

Expandable Querying​

Expandable querying is a feature in our API that allows clients to "expand" specific fields in the response into their full object representations. This helps reduce the number of API calls the client needs to make by embedding related objects directly in the response.

This is done by specifying the expand query parameter with a comma-separated list of fields to expand. These can also be "nested" expansions, which are expansions within expanded objects. The API supports a maximum depth of 4 nested expansions. The Expandable badge, throughout the documentation, indicates that the field can be expanded.

For example, when retrieving Survey Objects, you can specify expand=steps which will return the full Step objects in place of the IDs.

Without Expansion
GET /v2/businesses/bus_xxx/surveys/sur_xxx

{
  "data": {
    "id": "sur_xxx",
    "business": "bus_xxx",
    "steps": ["step_xxx"],
    ...
  },
  "object": "survey"
}
With Expansion
GET /v2/businesses/bus_xxx/surveys/sur_xxx?expand=steps

{
  "data": {
    "id": "sur_xxx",
    "business": "bus_xxx",
    "steps": [
      {
        "id": "step_xxx",
        "type": "metrics",
        "metrics": {
          "metrics": ["mtr_xxx"]
        },
        ...
      }
    ],
    ...
  },
  "object": "survey"
}
With Nested Expansion
GET /v2/businesses/bus_xxx/surveys/sur_xxx?expand=steps.metrics

{
  "data": {
    "id": "sur_xxx",
    "business": "bus_xxx",
    "steps": [
      {
        "id": "step_xxx",
        "type": "metrics",
        "metrics": {
          "metrics": [
            {
              "id": "mtr_xxx",
              "name": "Ambiance",
              ...
            }
          ]
        },
        ...
      }
    ],
    ...
  },
  "object": "survey"
}