Convert JSON object to query string

APIs, front-end routers, and analytics pipelines often hold filters and form fields as a simple JSON map and still need a correctly encoded query string for the address bar or an outbound HTTP client. This capability accepts one flat JSON object, coerces each scalar value to text, percent-encodes every key and value, and returns the ready-to-append query string together with ordered pairs and a normalized string map. Nested objects and arrays are rejected with invalid_input so callers never emit half-structured garbage that looks like a valid URL.

From a flat object to an encoded query string

A URL query string is a sequence of name-equals-value fields joined by ampersands, optionally preceded by a question mark after the path. The result is a query string without inventing extra separators from raw special characters. Empty objects produce an empty query string and a lone question-mark prefix form, which is useful for tests that assert no parameters rather than inventing a dummy key. Length limits on key count and total serialized size keep pathological maps from exhausting memory in the free browser path. When your source of truth is already a JSON object—for example a filter state, a form model, or a config map—you need a deterministic way to turn that map into the wire format browsers and servers expect. This capability walks the object’s own keys in insertion order, converts each scalar value to a stable string (booleans become true or false, finite numbers use ordinary decimal notation, null becomes an empty value), and applies encodeURIComponent to every key and every value so spaces become percent-twenty, ampersands become percent-twenty-six, and Unicode survives transit. Nested objects and arrays are intentionally unsupported: a query parameter is a flat key-value pair, and serializing nested structure into a single opaque string would hide mistakes that callers usually want to fix before the request leaves the client. Because the path is pure string and object work with no network, no random seeds, and no wall-clock timestamps, identical inputs always produce identical JSON. Successful API pricing is the published base of $0.002 per item, and validation failures do not consume prepaid balance.

Input contract, response shape, and error behaviour

The value must be a flat object whose properties are strings, numbers, booleans, or null. Non-finite numbers (NaN and Infinity) are rejected because they have no standard portable form in query strings. Example: name Ada Lovelace, city London, active true, and score forty-two produce a four-parameter string with spaces and any reserved characters percent-encoded. POST a JSON body with a required object field (aliases json, data, params, map, fields). You may also pass object as a JSON text string that parses to such a map. Arrays at the top level, null, scalars, and any nested object or array value fail with invalid_input and a clear English message naming the bad key when relevant. On success the response includes query (the encoded string without a leading question mark), query_with_prefix (the same string with a leading question mark, or a lone question mark when there are no keys), count (the number of parameters), pairs (an ordered array of key and value strings after scalar coercion but before encoding), and object (a last-wins string map of those coerced values). Classic failure: send nested filters under a key such as filter equals an object and receive invalid_input instead of a silently broken URL. Successful API pricing is the published base of $0.002 per item; validation failures are not billed.

Where JSON-to-query conversion earns its keep

Curriculum authors teaching web foundations want a dedicated landing for object-to-query serialization rather than burying the topic under a bidirectional parser, because search intent differs: people holding a JSON map want encoding, not parse mode options.