# Zeiträume und Zeitzonen (https://webmetic.de/docs/api/zeitraeume-und-zeitzonen)

Ein Zeitraum besteht aus `from_date` und `to_date`. Wenn Sie zum Beispiel alle Unternehmen sehen wollen, die im Oktober Ihre Website besucht haben, senden Sie `from_date=2026-10-01&to_date=2026-10-31`.

Der Zeitraum filtert nach dem Beginn eines Besuchs, nicht nach den einzelnen Seitenaufrufen darin.

## Vom Datum zum Ergebnis [#vom-datum-zum-ergebnis]

1. **Datum angeben**: Sie senden ein Datum, eine Uhrzeit oder eine relative Angabe wie `-7 days`.
2. **In UTC umrechnen**: Webmetic rechnet die Angabe in einen Zeitpunkt in UTC um.
3. **Besuche filtern**: Webmetic wählt die Sessions, die im Zeitraum begonnen haben.
4. **Antwort lesen**: Alle Zeitangaben in der Antwort stehen in UTC.

## Parameter und Standardwerte [#parameter-und-standardwerte]

Alle acht Visitor-Intelligence-Endpunkte nehmen die beiden Parameter in der Query an: `/company-sessions`, `/company`, `/company_nace`, `/session`, `/session_user_data`, `/intensive-visits`, `/returning-visits` und `/new-visits`. Enrichment, Ansprechpartner und Webhooks haben keine Zeitraum-Parameter.

- **`from_date`**: Beginn des Zeitraums. Ohne Angabe gilt `-30 days`, also 30 Tage vor dem Zeitpunkt der Anfrage.
- **`to_date`**: Ende des Zeitraums. Ohne Angabe gilt `now`, der Zeitpunkt der Anfrage.

## Erlaubte Formate [#erlaubte-formate]

Beide Parameter verstehen dieselben Formate:

| Format | Beispiel | Bedeutung |
| --- | --- | --- |
| ISO-Datum | `2026-10-21` | Der ganze 21. Oktober in UTC |
| ISO-Datum mit Uhrzeit | `2026-10-21T08:00:00Z` | Genau dieser Zeitpunkt |
| Relative Angabe | `-7 days`, `-12 hours` | So lange vor dem Zeitpunkt der Anfrage |
| Jetzt | `now` | Der Zeitpunkt der Anfrage |
| Tageswörter | `heute`/`today`, `gestern`/`yesterday` | Der Kalendertag in deutscher Zeit; als `to_date` bedeutet `heute` jetzt |
| Deutsches Datum | `21.10.2026` | Wie `2026-10-21` |

Relative Angaben kennen `days`, `hours`, `minutes` und `years`, aber keine Wochen und Monate. Für eine Woche oder einen Monat geben Sie deshalb zwei Daten an. Schreiben Sie `now` immer klein, denn die API versteht `NOW` nicht.

Wenn die API einen Wert nicht lesen kann, antwortet sie mit Status `400` und dem Code `INVALID_DATE`. Mehr dazu unter [Fehler](https://webmetic.de/docs/api/fehler).

## Anfang und Ende [#anfang-und-ende]

- **Beginn**: `from_date` gehört zum Zeitraum, deshalb ist eine Session mit genau diesem Startzeitpunkt enthalten.
- **Ende**: `to_date` gehört nicht mehr dazu, weil der Zeitraum direkt vor diesem Zeitpunkt endet.
- **Datum ohne Uhrzeit**: Als `to_date` zählt der ganze Tag mit, deshalb schließt `to_date=2026-10-31` den 31. Oktober ein.

Ein Unternehmen erscheint, wenn mindestens eine seiner Sessions im Zeitraum begonnen hat. Ein Besuch, der vor `from_date` begann, fehlt auch dann, wenn er in den Zeitraum hineinreicht.

`/session_user_data` liefert alle Seitenaufrufe einer Session, die im Zeitraum begonnen hat.

## Zeitzonen [#zeitzonen]

Webmetic rechnet in UTC und liest auch ein ISO-Datum oder eine ISO-Uhrzeit ohne Zeitzone als UTC. Empfohlen: Geben Sie Zeitpunkte als ISO-Wert mit `Z` an, weil sie dann eindeutig sind.

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

```js tab="JavaScript" tab-group="lang"
const params = new URLSearchParams({
  domain: 'ihre-website.de',
  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_IHR_API_SCHLUESSEL' },
});
const data = await res.json();
```

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

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

Sie können auch einen Versatz angeben, zum Beispiel `+02:00`. In einer URL steht `+` aber für ein Leerzeichen, und die API liest den Wert dann ohne Fehlermeldung falsch. Schreiben Sie deshalb `%2B` oder lassen Sie Ihren HTTP-Client den Parameter kodieren:

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

## Zeitangaben in Antworten [#zeitangaben-in-antworten]

- **API-Antworten**: In Antworten auf GET-Anfragen stehen Zeitstempel in ISO 8601 in UTC, ohne `Z` und ohne Versatz, zum Beispiel `2026-08-22T08:20:26.384000`. Lesen Sie die Werte als UTC. JavaScript liest einen Zeitstempel ohne Suffix als Ortszeit. Hängen Sie deshalb vor dem Parsen ein `Z` an, wenn der Wert keinen Versatz hat: `new Date(value + "Z")`.
- **Sekundenbruchteile**: Webmetic lässt Sekundenbruchteile weg, wenn sie null sind, zum Beispiel `2026-10-01T08:00:00`. Lesen Sie Zeitstempel deshalb mit einem ISO-Parser und nicht nach fester Position.
- **Webhooks**: Zugestellte Ereignisse enthalten jede Zeitangabe in UTC mit `Z`.

## Nächste Schritte [#nächste-schritte]

- [Paginierung](https://webmetic.de/docs/api/paginierung): Große Zeiträume Seite für Seite abrufen.
- [Webhooks](https://webmetic.de/docs/api/webhooks): Neue Besuche zustellen lassen, statt sie abzufragen.
- [Fehler](https://webmetic.de/docs/api/fehler): Nachlesen, was `INVALID_DATE` und die anderen Fehlercodes bedeuten.