Ferret — Export Formats

Every endpoint supports three output formats via the ?format= query parameter: JSON (default), CSV, and XML.

Quick reference

The format works on any endpoint that returns a list — search, extract, crawl, French data, business endpoints:

curl "http://localhost:9093/search/bing?q=rust&format=csv"
curl "http://localhost:9093/french/dvf?q=75001&format=xml"
curl "http://localhost:9093/seo/audit?q=example.com&format=json"

JSON (default)

The default Tavily-compatible response shape. Omit ?format= to get JSON, or set it explicitly:

curl "http://localhost:9093/search/bing?q=rust&format=json"

{
  "success": true,
  "items": [
    {
      "title": "Rust Programming Language",
      "url": "https://www.rust-lang.org",
      "snippet": "A language empowering everyone to build reliable and efficient software.",
      "source": "bing"
    },
    {
      "title": "The Rust Programming Language",
      "url": "https://doc.rust-lang.org/book/",
      "snippet": "An introductory book about Rust...",
      "source": "bing"
    }
  ],
  "time_ms": 142
}

JSON is the right choice when:

• You’re calling from code (Python, JS, Go, …)
• The result feeds an LLM prompt
• You need nested objects (business endpoints, research summaries)

CSV

Tabular output with a header row. Each item becomes a row; nested objects are flattened:

curl "http://localhost:9093/search/bing?q=rust&format=csv"

title,url,snippet,source
"Rust Programming Language","https://www.rust-lang.org","A language empowering everyone...","bing"
"The Rust Programming Language","https://doc.rust-lang.org/book/","An introductory book about Rust...","bing"

CSV is the right choice when:

• You’re pasting results into Excel or Google Sheets
• Feeding a BI tool (Metabase, Tableau, Looker)
• Building a quick data export

Tip: For endpoints that return many flat items (DVF real estate transactions, SIRENE records), CSV is dramatically more compact than JSON.

XML

XML serialization with a root <response> element:

curl "http://localhost:9093/search/bing?q=rust&format=xml"

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <success>true</success>
  <items>
    <item>
      <title>Rust Programming Language</title>
      <url>https://www.rust-lang.org</url>
      <snippet>A language empowering everyone...</snippet>
      <source>bing</source>
    </item>
    <item>
      <title>The Rust Programming Language</title>
      <url>https://doc.rust-lang.org/book/</url>
      <snippet>An introductory book about Rust...</snippet>
      <source>bing</source>
    </item>
  </items>
  <time_ms>142</time_ms>
</response>

XML is the right choice when:

• Integrating with legacy SOAP / enterprise systems
• Producing an RSS-style feed
• Your stack parses XML natively (.NET, Java JAXB)

Combining with other parameters

format is independent of other query parameters and composes cleanly:

# Multi-engine search, CSV output, 1 page, no cache
curl "http://localhost:9093/search?q=rust&format=csv&pagecount=1&no_cache=true"

# French DVF transactions as XML
curl "http://localhost:9093/french/dvf?q=75001&format=xml"

# SEO audit as JSON (the structured form for your pipeline)
curl "http://localhost:9093/seo/audit?q=example.com&format=json"

# The /llm variant always returns markdown text — format= has no effect there
curl "http://localhost:9093/seo/audit/llm?q=example.com"

The /llm business-endpoint variants always return a markdown prompt regardless of format= — they exist specifically to produce text for LLM consumption. See Business endpoints.

In the SDKs

Python

from ferret import FerretClient

client = FerretClient("http://localhost:9093")

csv_text = client.search("rust", format="csv")    # str
xml_text = client.search("rust", format="xml")    # str
json_obj = client.search("rust", format="json")   # dict (default)

JavaScript

import { FerretClient } from 'ferret-client';

const client = new FerretClient('http://localhost:9093');

const csv = await client.search('rust', { format: 'csv' }); // string
const xml = await client.search('rust', { format: 'xml' }); // string
const json = await client.search('rust', { format: 'json' }); // object

Related

• API Reference — full endpoint list
• Business endpoints — the 17 cross-cutting analyses
• Python SDK / JavaScript SDK