Documentation

Real Fake Data API Reference

A small, predictable REST API for generating realistic synthetic Polish data — deterministic when you need it, random when you do not.

Getting started

Quickstart

Every endpoint is a plain HTTPS GET request that returns a JSON envelope with a data record and a meta block. Pass a seed to get the same record back every time — perfect for stable test fixtures. The example below fetches a single Polish address.

terminal

curl https://realfakedata-api.onrender.com/v1/pl/address \
  -G --data-urlencode "seed=42"

Getting started

Authentication

Authenticate every request with your API key in the Authorization header as a Bearer token. You can create and rotate keys from your dashboard; each key is scoped to a single environment.

Authorization header

Authorization: Bearer rfd_live_3f9a••••••2c71

Keep your secret keys server-side. Never embed a live key in client-side code or commit it to version control.

API reference

GET /v1/pl/address

Returns a realistic Polish address drawn from real cities and streets, complete with a valid postal code and the matching TERYT administrative codes. All parameters are optional.

Parameter	Type	Description
seed	string	Optional. Makes the response deterministic.
teryt	string	Optional. Restrict output to a region (1–7 digit prefix).

Request

GET /v1/pl/address

curl https://realfakedata-api.onrender.com/v1/pl/address \
  -G --data-urlencode "seed=7421" \
  -H "Authorization: Bearer rfd_live_3f9a••••••2c71"

Response

application/json200 OK

{
  "data": {
    "streetFullName": "ul. Długa",
    "buildingNumber": "153",
    "postalCode": "00-632",
    "cityName": "Warszawa",
    "municipalityName": "Warszawa",
    "countyName": "Warszawa",
    "voivodeshipName": "mazowieckie",
    "terytCodes": {
      "voivodeshipCode": "14",
      "countyCode": "1465",
      "municipalityCode": "146501",
      "cityCode": "0918123",
      "streetCode": "08522"
    }
  },
  "meta": {
    "seed": 7421,
    "generatorId": "pl.address"
  }
}