# Date ranges and time zones (https://webmetic.de/docs/en/api/zeitraeume-und-zeitzonen)

A date range consists of `from_date` and `to_date`. If you want every company that visited your website in October, for example, you send `from_date=2026-10-01&to_date=2026-10-31`.

The range filters by the start of a visit, not by the individual page views within it.

## From date to result [#from-date-to-result]

1. **Send a date**: You send a date, a time, or a relative value such as `-7 days`.
2. **Convert to UTC**: Webmetic turns it into a point in time in UTC.
3. **Filter visits**: Webmetic picks the sessions that started within the range.
4. **Read the response**: Every time in the response is in UTC.

## Parameters and defaults [#parameters-and-defaults]

All eight Visitor Intelligence endpoints take both parameters in the query: `/company-sessions`, `/company`, `/company_nace`, `/session`, `/session_user_data`, `/intensive-visits`, `/returning-visits`, and `/new-visits`. Enrichment, contacts, and webhooks have no date parameters.

- **`from_date`**: start of the range. If you leave it out, it's `-30 days`, which means 30 days before the time of the request.
- **`to_date`**: end of the range. If you leave it out, it's `now`, the time of the request.

## Accepted formats [#accepted-formats]

Both parameters accept the same formats:

| Format | Example | Meaning |
| --- | --- | --- |
| ISO date | `2026-10-21` | All of October 21 in UTC |
| ISO date with time | `2026-10-21T08:00:00Z` | Exactly this point in time |
| Relative value | `-7 days`, `-12 hours` | That long before the time of the request |
| Now | `now` | The time of the request |
| Day words | `heute`/`today`, `gestern`/`yesterday` | The calendar day in German time; as `to_date`, `today` means now |
| German date | `21.10.2026` | Same as `2026-10-21` |

Relative values know `days`, `hours`, `minutes`, and `years`, but not weeks or months. For a week or a month, give two dates instead. Always write `now` in lowercase, because the API doesn't understand `NOW`.

If the API can't read a value, it answers with status `400` and the code `INVALID_DATE`. For details, see [Errors](https://webmetic.de/docs/en/api/fehler).

## Start and end [#start-and-end]

- **Start**: `from_date` belongs to the range, so a session that starts exactly at that time is included.
- **End**: `to_date` no longer belongs to it, because the range ends right before that time.
- **Date without time**: as `to_date`, the whole day counts, so `to_date=2026-10-31` includes October 31.

A company appears when at least one of its sessions started within the range. A visit that began before `from_date` is left out, even if it runs into the range.

`/session_user_data` returns all page views of a session that started within the range.

## Time zones [#time-zones]

Webmetic works in UTC and also reads an ISO date or ISO time without a time zone as UTC. We recommend sending points in time as ISO values with `Z`, because then they're unambiguous.

```bash tab="cURL" tab-group="lang"
curl "https://hub.webmetic.de/company?domain=your-website.com&from_date=2026-10-01T00:00:00Z&to_date=2026-11-01T00:00:00Z" \
  -H "Authorization: wmtc_YOUR_API_KEY"
```

```js tab="JavaScript" tab-group="lang"
const params = new URLSearchParams({
  domain: 'your-website.com',
  from_date: '2026-10-01T00:00:00Z',
  to_date: '2026-11-01T00:00:00Z',
});
const res = await fetch(`https://hub.webmetic.de/company?${params}`, {
  headers: { Authorization: 'wmtc_YOUR_API_KEY' },
});
const data = await res.json();
```

```python tab="Python" tab-group="lang"
import requests

res = requests.get(
    "https://hub.webmetic.de/company",
    params={
        "domain": "your-website.com",
        "from_date": "2026-10-01T00:00:00Z",
        "to_date": "2026-11-01T00:00:00Z",
    },
    headers={"Authorization": "wmtc_YOUR_API_KEY"},
)
data = res.json()
```

You can also give an offset, for example `+02:00`. In a URL, though, `+` stands for a space, and the API then misreads the value without an error. So write `%2B` or let your HTTP client encode the parameter:

```bash
curl -G "https://hub.webmetic.de/session" \
  -H "Authorization: wmtc_YOUR_API_KEY" \
  --data-urlencode "domain=your-website.com" \
  --data-urlencode "from_date=2026-10-21T00:00:00+02:00" \
  --data-urlencode "to_date=2026-10-22T00:00:00+02:00"
```

## Times in responses [#times-in-responses]

- **API responses**: in responses to GET requests, timestamps are ISO 8601 in UTC, without `Z` and without an offset, for example `2026-08-22T08:20:26.384000`. Read the values as UTC. JavaScript reads a timestamp without a suffix as local time. So append a `Z` before parsing if the value has no offset: `new Date(value + "Z")`.
- **Fractions of a second**: Webmetic leaves them out when they're zero, for example `2026-10-01T08:00:00`. So read timestamps with an ISO parser and not by fixed position.
- **Webhooks**: delivered events contain every time in UTC with `Z`.

## Next steps [#next-steps]

- [Pagination](https://webmetic.de/docs/en/api/paginierung): Fetch large ranges page by page.
- [Webhooks](https://webmetic.de/docs/en/api/webhooks): Receive new visits instead of polling for them.
- [Errors](https://webmetic.de/docs/en/api/fehler): Look up what `INVALID_DATE` and the other error codes mean.