# Data format tools API

> JSON, YAML, TOML, CSV and XML to each other; text and JSON differences; spreadsheets to JSON and back.

Everyday conversions for scripts and pipelines. What you send is never logged.

Base URL `https://api.dharun.dev`. No API key needed for most endpoints; a free key (https://api.dharun.dev/keys) raises the limits, and the model endpoints marked below will need one. Answers are JSON, `{ "data": ..., "meta": { ... } }`, and errors are `{ "error": { "code", "message" } }` with a matching HTTP status. Rate limit: 600 units a minute per address without a key, 3000 per key; the `RateLimit-*` headers say what is left.

## Convert between data formats

`GET /v1/convert`, also `POST`

Reads JSON, YAML, TOML, CSV or XML and writes any of them. The input format is guessed when from is not given.

POST body: The document, as text/plain, or JSON {"text": "...", "from": "yaml", "to": "json"}. Send it as `text/plain`, or as JSON `{"text": "..."}` with the other options beside it.

What you send is never written to the log, and the answer is not cached.

Parameters:

- `text` (query): The document, for short ones.
- `from` (query): Its format. Default: guessed. One of: json, yaml, toml, csv, xml.
- `to` (query): Default json. One of: json, yaml, toml, csv, xml.
- `raw` (query): true answers with the converted document itself.

Example: https://api.dharun.dev/v1/convert?to=yaml&text=%7B%22name%22%3A%22India%20API%22%2C%22tags%22%3A%5B%22a%22%2C%22b%22%5D%7D&utm_medium=docs-md

Response, with lists and long text shortened:

```json
{
  "data": {
    "from": "json",
    "output": "name: India API\ntags:\n  - a\n  - b\n",
    "to": "yaml"
  },
  "meta": {
    "note": "XML elements become keys, repeated ones lists, attributes keys starting with @. CSV rows become objects named by the first line. raw=true answers with the conve…"
  }
}
```

## Compare two texts or JSON documents

`POST /v1/diff`

Text: a unified patch and counts of added and removed lines. JSON: a list of JSON Patch (RFC 6902) changes with the old values.

Send: JSON: {"a": "...", "b": "...", "mode": "text" or "json", "context": 3, "changes": false}. a and b may be JSON values for mode json.

What you send is never written to the log, and the answer is not cached.

Example: `POST` https://api.dharun.dev/v1/diff?utm_medium=docs-md

Example body (invoice.json):

```json
{"a": "rice\ndal\noil\n", "b": "rice\nmoong dal\noil\nsalt\n"}
```

Response:

```json
{
  "data": {
    "same": false,
    "added": 2,
    "removed": 1,
    "patch": "--- a\n+++ b\n@@ -1,3 +1,4 @@\n rice\n-dal\n+moong dal\n oil\n+salt\n"
  },
  "meta": {}
}
```

## Spreadsheet to JSON

`POST /v1/sheet/to-json`

Every sheet of an XLSX workbook (or a CSV file) as records named by the first row. Options go in the query string, or as form fields when the file is sent as multipart/form-data.

Send: An XLSX workbook or a CSV file, up to 10 MB. Post the file as the request body, or as `multipart/form-data`. Sample file: https://api.dharun.dev/samples/table.csv

What you send is never written to the log, and the answer is not cached.

Parameters:

- `sheet` (query): Only this sheet.
- `header` (query): false gives rows of values instead of records. Default true.

Example: `POST` https://api.dharun.dev/v1/sheet/to-json?utm_medium=docs-md

Response, with lists and long text shortened:

```json
{
  "data": [
    {
      "columns": [
        "pincode",
        "office",
        "district"
      ],
      "name": "Sheet1",
      "records": [
        {
          "district": "Namakkal",
          "office": "Namakkal H.O",
          "pincode": "637001",
          "state": "Tamil Nadu"
        },
        {
          "district": "Chennai",
          "office": "Chennai G.P.O.",
          "pincode": "600001",
          "state": "Tamil Nadu"
        },
        {
          "district": "New Delhi",
          "office": "New Delhi G.P.O.",
          "pincode": "110001",
          "state": "Delhi"
        }
      ],
      "rows": 4
    }
  ],
  "meta": {
    "note": "Cell values as the sheet shows them (formatted). With header=false, rows of values instead of records named by the first row."
  }
}
```

## JSON to a spreadsheet

`POST /v1/sheet/from-json`

Records in, an XLSX workbook out, with the header row frozen.

Send: JSON: {"records": [{...}]} for one sheet, or {"sheets": [{"name": "...", "records": [...]}, {"name": "...", "values": [[...]]}]}.

What you send is never written to the log, and the answer is not cached.

Example: `POST` https://api.dharun.dev/v1/sheet/from-json?utm_medium=docs-md (returns an XLSX workbook)

Example body (invoice.json):

```json
{"records": [{"pincode": "637001", "district": "Namakkal"}, {"pincode": "600001", "district": "Chennai"}]}
```