---
title: "Suggests an optimal fielding time range for a locale"
method: GET
path: "/demand/intelligent-calendar/suggest-time-range"
tags: ["Intelligent Calendar"]
---

# Suggests an optimal fielding time range for a locale

`GET /demand/intelligent-calendar/suggest-time-range`

## Request

- Base URL: `https://api.cint.com/v1`
- URL: `https://api.cint.com/v1/demand/intelligent-calendar/suggest-time-range`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/cint/apis/demand-api/docs/demand/intelligent-calendar/suggest-time-range/get.ts> (a function with typed inputs; its response is checked against the schema)

Suggests an optimal time range to field a target group in a specific locale, taking into account local holidays and respondent activity patterns.

How to specify a time range:

* To get a suggestion for a specific duration starting from now, provide the `days` parameter.
* To get a suggestion within a specific date window, provide both the `start` and `end` parameters.

These options are mutually exclusive. A request that combines `days` with `start` or `end`, or that provides neither, returns a 400 error.

## Query parameters

- `days` integer
- `start` string, date-time
- `end` string, date-time
- `locale` string, required: Unique text code of the locale.

## Response `200`

The suggested time range was calculated successfully.

- SuggestedTimeRangeResponse: A suggested time range for fielding, including holiday and timezone information.
  - `suggested_start` string, date-time: Starting timestamp of the suggested time range.
  - `suggested_end` string, date-time: Ending timestamp of the suggested time range.
  - `holidays` object[]: List of holidays in the suggested time range.
    - `date` string: The date of the holiday in YYYY-MM-DD format.
    - `name` string: The name of the holiday.
    - `respondent_rate` number, double: The projected respondent activity rate on this day, relative to a normal day (1.0).
    - `completes_rate` number, double: The projected survey completion rate on this day, relative to a normal day (1.0).
  - `timezone` string: The IANA time zone identifier for the suggested range (e.g., "Europe/London").

## Other responses

- `400`: A request is not valid and can't be processed.
- `401`: Authentication credentials are missing or invalid, or the caller doesn't have the role required for this operation.
- `500`: A request failed due to an internal error.

---

[API](https://skmtc.dev/cint/apis/demand-api.md) - [All operations](https://skmtc.dev/cint/apis/demand-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cint/apis/demand-api/revisions/077a4bdda5cb?raw)