API & data

Versioned datasets, deterministic sampling, and normalized live API tools with clear source attribution.

API v1 Format JSON

Private by default

Algorithmic tools such as hashing, validation, formatting and number generation still run locally. Data-backed randomizers request only the small sample they need from Randomly's own API. User-entered values are not sent to upstream dataset providers. Live discovery tools send only their visible filters—not unrelated local tool input—to the named source shown with every result.

Dataset API

Discover published datasets at /api/v1/datasets, read a manifest at /api/v1/datasets/cities, or request a sample from /api/v1/datasets/cities/random?count=5&seed=demo. A response includes the source version, license, attribution, publication time and the seed used for the draw.

Live random tools

Tools backed by changing public APIs use /api/v1/tools/:slug/random?count=1. Responses contain items, the upstream source, and cache/fetch metadata. Requests are validated, capped at eight results, timed out, and cached within each provider's practical limits.

Licensing and reuse

Public availability does not automatically grant reuse rights. Each dataset has its own license and attribution requirements in the manifest. Follow those terms when reusing results. Datasets with unknown, noncommercial-only or unresolved rights are quarantined and are not published through the production API.

Availability and limits

The public endpoint currently allows up to 100 items per request. Large datasets are stored as immutable, versioned shards and served from Randomly's cache, so upstream API outages do not interrupt generation. The legacy files under /data/ remain temporarily available as a browser fallback while datasets complete migration.

Randomly has two kinds of data-backed tools. Some select from versioned datasets that Randomly publishes and serves through its own API. Others request current information from a named public source, then return a small normalized result for the tool. The source name shown on a result is there so you can understand where it came from and follow it when you need the original record.

Most calculators, encoders, generators, and validators do not use this API at all. They run in your browser. The difference matters: a local UUID or hash never needs to leave the page, while a random city or live market result requires a request for source data.

Use the dataset API for reproducible samples

The dataset endpoint lists the available published datasets, and each dataset has a manifest with its source version, licence, attribution, and publication time. Add a seed when you need the same random sample again. The response returns that seed with the sampled items, which makes a demo, test case, or bug report easier to reproduce.

A dataset response is JSON. It is intended for small, practical samples rather than bulk scraping. Respect the licence and attribution shown in the manifest, especially when a dataset is incorporated into another product or published work.

Live tools are a separate interface

Live discovery pages use the tools endpoint. They return normalised items plus source and cache information, but their values can change as the upstream source changes. A current price, deal, weather observation, or event record is not frozen simply because you saw it here.

The API validates inputs and caps tool results so a single page cannot request an unlimited batch. When a provider is unavailable, a live tool may show an error or a cached result. The displayed source is still the right place to verify a time-sensitive decision.

Privacy, attribution, and safe reuse

A local tool processes its input in your browser. A data-backed tool sends only the filters needed for its result, such as a topic, country, or price limit; it does not send unrelated values from another tool. See the Privacy page for the site's analytics and request-handling details.

Public data is not automatically free of conditions. Check each dataset manifest or linked source before copying a result into a project. Randomly does not grant rights that the original source has not granted.

Frequently asked questions

Where can I list the published datasets?

Request /api/v1/datasets to receive the available dataset list and their public metadata.

How do I get a repeatable random sample?

Pass a seed to a dataset random endpoint. The response includes the seed used so the same sample can be requested again.

Are live tool results guaranteed to be current?

No. Live results depend on their upstream source and cache state. Use the linked source to verify time-sensitive information.

Can I reuse API results in my own project?

Check the dataset manifest or source licence first. Public availability does not remove attribution or reuse requirements.

Do all Randomly tools call an API?

No. Many tools, including local generators, validators, and converters, run entirely in the browser without sending the value you enter to a Randomly API.