# Timestamp Converter - Unix, ISO, RFC 2822, Any Timezone (`eliai/timestamp-converter`) Actor

Any timestamp shape in (unix s/ms auto-detected, ISO, "now") — every form out: unix, ISO 8601, RFC 2822, DST-correct IANA timezone rendering, real ISO week numbers, day-of-year, leap flag, relative time. $0.0004 per conversion (cost-plus floor, no paid rival measured); bad inputs never charged.

- **URL**: https://apify.com/eliai/timestamp-converter.md
- **Developed by:** [Broke to Built](https://apify.com/eliai) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.32 / 1,000 converted timestamps

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Timestamp Converter - Unix, ISO 8601, RFC 2822 and Any IANA Timezone

**Send any timestamp shape, get every representation back at once.** Unix seconds, Unix milliseconds
(auto-detected), ISO 8601, RFC 2822 date strings, or the literal `"now"` go in; Unix s and ms, ISO
8601, RFC 2822, a DST-correct rendering in any IANA timezone, day of week, day of year, ISO week
number, leap-year flag and humanized relative time come out. Up to 50 per run. $0.0004 per
conversion. Unparseable inputs are recorded free.

Log correlation across systems that each picked a different format, scheduling, invoice date
handling, and agents that need to reason about "when" without a date library.

### What you get

Per input, one record with these exact fields:

- `ok` - true when the value parsed
- `input` - the value you sent
- `timezone` - the IANA zone used for the human rendering
- `unixSeconds`, `unixMillis`
- `iso8601`, `rfc2822`, `utcString`
- `timezoneFormatted` - the same instant rendered in your chosen zone
- `dayOfWeek`, `dayOfYear`, `weekNumber` (real ISO 8601 week rule), `isLeapYear`
- `relativeFromNow` - "in 3 days", "2 hours ago" (`relative` is an alias)
- `error` - present instead of the conversions when the value could not be parsed. Never charged.

### Example 1: a Unix timestamp in a US timezone

Input:

```json
{ "input": 1700000000, "timezone": "America/New_York" }
```

Output (real run, 2026-08-15):

```json
{
  "input": "1700000000",
  "ok": true,
  "timezone": "America/New_York",
  "unixSeconds": 1700000000,
  "unixMillis": 1700000000000,
  "iso8601": "2023-11-14T22:13:20.000Z",
  "rfc2822": "Tue, 14 Nov 2023 22:13:20 GMT",
  "utcString": "Tue, 14 Nov 2023 22:13:20 GMT",
  "timezoneFormatted": "Tue, Nov 14, 2023, 17:13:20 EST",
  "dayOfWeek": "Tuesday",
  "dayOfYear": 318,
  "weekNumber": 46,
  "isLeapYear": false,
  "relativeFromNow": "2 years ago"
}
```

22:13 UTC renders as 17:13 EST - the offset comes from real IANA timezone data, so it is correct for
that date's DST state rather than a fixed offset.

### Example 2: a leap day, and a value that will not parse

Input:

```json
{ "inputs": ["2024-02-29T12:00:00Z", "not-a-date"], "timezone": "America/New_York" }
```

Output (real run, same session, trimmed):

```json
[
  {
    "input": "2024-02-29T12:00:00Z", "ok": true,
    "unixSeconds": 1709208000,
    "timezoneFormatted": "Thu, Feb 29, 2024, 07:00:00 EST",
    "dayOfWeek": "Thursday", "dayOfYear": 60, "weekNumber": 9, "isLeapYear": true
  },
  { "input": "not-a-date", "ok": false, "error": "unrecognized timestamp/date format" }
]
```

The bad value does not fail the run and is **not charged**; the good one converts normally.

**When `inputs` is filled, the single `input` field is ignored** - you are charged for the values you
listed and nothing else.

### Example 3: mixed shapes in one batch

Input:

```json
{ "inputs": [1516239022, 1700000000000, "2024-01-15", "now"], "timezone": "Asia/Tokyo" }
```

Seconds, milliseconds, a date string and `"now"` can be mixed freely - each is detected on its own.
`1516239022` is read as seconds and `1700000000000` as milliseconds, because values at or above 1e11
are treated as milliseconds.

### Pricing

**$0.0004 per timestamp converted.** No start fee. One event covers one value parsed and returned in
every representation above - Unix s and ms, ISO, RFC 2822, the timezone rendering, all the calendar
fields and the relative time. Unparseable inputs are recorded with the reason and never charged.

Honest comparison: a store search on 2026-08-07 for a timestamp converter returned transcript
scrapers, not converters - there is no directly comparable paid incumbent to quote a price against,
so this sits at the floor of our ladder rather than undercutting a named competitor.

Also honest: every language has a date library, and your own code can do this for free. Pay for it
when you want a hosted conversion step in a no-code pipeline, a batch of mixed-format log timestamps
normalized in one call, or a tool an AI agent can call instead of doing date arithmetic in its head -
which is a thing language models are famously bad at.

### When NOT to use this

- **Per-row timezones.** One `timezone` applies to the whole run. If each record needs its own zone,
  send one run per zone, or convert from the `iso8601` field on your side.
- **Ambiguous local date strings.** `03/04/2024` is March 4th or April 3rd depending on where you
  live, and JavaScript's parser will pick one. Send ISO 8601 for anything that matters.
- **Dates before roughly 1973 expressed in milliseconds.** The seconds-versus-milliseconds detection
  is by magnitude, and that is the one region where the two overlap. Send those as ISO strings.
- **Date arithmetic.** This converts and describes an instant; it does not add business days, compute
  durations between two timestamps, or handle recurrence rules.
- **A single conversion while you are debugging.** Any online epoch converter is free. This is for
  batches, pipelines and agents.

### Honest limits

- Unix auto-detection by magnitude: values at or above 1e11 are read as milliseconds, below that as
  seconds.
- Date-string parsing follows JavaScript `Date` semantics. ISO 8601 is fully reliable; locale-shaped
  strings follow JS rules.
- Calendar fields (`dayOfWeek`, `dayOfYear`, `weekNumber`, `isLeapYear`) are computed in **UTC** for
  determinism, while `timezoneFormatted` renders in your chosen zone. Near midnight these can
  therefore describe different calendar days - by design, so the calendar fields never depend on a
  zone you did not intend.
- `relativeFromNow` is computed at run time, so it ages the moment the run finishes.
- Up to 50 inputs per run. An invalid timezone name stops the run with a guidance record rather than
  silently substituting UTC.

### FAQ

**How do I convert a Unix timestamp to a readable date with a timezone?**
Send `{"input": 1700000000, "timezone": "America/New_York"}`. `timezoneFormatted` is the human form;
`iso8601` is the machine form. Any IANA zone name works.

**Does it handle both seconds and milliseconds?**
Yes, automatically, and both are always returned as `unixSeconds` and `unixMillis` so you can see
which way it read your input. If the ISO date comes back in 1970 or in the year 50,000, your value
was in the other unit - resend it as ISO.

**Which week number does it use?**
Real ISO 8601: weeks start on Monday and week 1 is the week containing the first Thursday. That means
January 1st can correctly be week 52 or 53 of the previous year, and this gets that right rather than
dividing the year by seven.

**Is daylight saving time handled correctly?**
Yes. Rendering goes through `Intl` with real IANA timezone data, so an instant in July renders as EDT
and one in November as EST, with the correct offset for each.

**Can I convert a batch of log timestamps at once?**
Yes - up to 50 per run in `inputs`, and the shapes can be mixed (seconds, milliseconds, ISO strings,
`"now"`). One record and one charge each; unparseable values are free.

**What does `"now"` do?**
Returns the current instant in every representation. Useful as a clock for an agent, or to get the
current ISO week number without any date math.

**Why did some rows come back `ok: false`?**
The value could not be parsed as a timestamp or a date. It is recorded with the reason and never
charged.

### Use from code or AI agents

```bash
curl -s "https://api.apify.com/v2/acts/EliAI~timestamp-converter/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -X POST -H 'Content-Type: application/json' \
  -d '{"input": "now", "timezone": "Asia/Tokyo"}'
```

Agents: connect [Apify MCP](https://mcp.apify.com) and call the `EliAI/timestamp-converter` tool.

- **Capability:** convert any timestamp shape into every standard representation plus calendar facts, timezone-aware
- **Required input:** `input` or `inputs`; optional `timezone` (IANA, default UTC)
- **Returns:** one record per input with all representations
- **Bounded:** 50 inputs per run; failures isolate per input
- **Side effects:** none

# Actor input Schema

## `input` (type: `string`):

A Unix timestamp (seconds or milliseconds, auto-detected), an ISO 8601 / RFC 2822 / date string, or the literal "now".

## `inputs` (type: `array`):

Multiple timestamps/dates to convert in one run. Each item is one Unix value, date string, or "now". When this list is filled, the single timestamp above is ignored, so you are only charged for the values you listed.

## `timezone` (type: `string`):

IANA timezone for the human-readable output (e.g. "America/New\_York", "Europe/London"). Defaults to UTC.

## `maxItems` (type: `integer`):

Maximum number of timestamps to convert in this run (cap).

## Actor input object example

```json
{
  "input": "1516239022",
  "inputs": [],
  "timezone": "UTC",
  "maxItems": 50
}
```

# Actor output Schema

## `results` (type: `string`):

Every item this run produced, as JSON.

## `resultsCsv` (type: `string`):

The same items as a spreadsheet-ready CSV.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "input": "1516239022",
    "timezone": "UTC"
};

// Run the Actor and wait for it to finish
const run = await client.actor("eliai/timestamp-converter").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "input": "1516239022",
    "timezone": "UTC",
}

# Run the Actor and wait for it to finish
run = client.actor("eliai/timestamp-converter").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "input": "1516239022",
  "timezone": "UTC"
}' |
apify call eliai/timestamp-converter --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,eliai/timestamp-converter"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/HNuddwobu8PSrChAA/builds/eu3kgjGvYOpI5IpZ8/openapi.json