--- title: "Making FRED navigable: a map for 800,000 series" description: "FRED is the best free economic archive on the internet, and it navigates like a library with no card catalog: text search, metadata in prose, licenses buried in notes. Anatomy of the Sugra macro layer: eight facets with honest counters, a measure field FRED does not have, licenses lifted into machine-readable fields, a release calendar that answers 'when is the next CPI', and four working recipes - including the France trap that fools half of all title-based picks." slug: making-fred-navigable status: published published_at: 2026-08-05 author: Arman Obosyan author_url: https://sugra.systems/about section: general primary_keyword: fred api facets macro data navigation hero_image: /blog/images/posts/making-fred-navigable-hero.jpg hero_alt: "A night sky of thousands of stars stands in for the FRED archive, with a milky way band and faint nebulae; an eight-star amber constellation labeled with the eight macro facets encloses a single teal star marked your series. The headline reads FRED data. Navigable at last." og_image: /blog/images/posts/making-fred-navigable-hero.jpg tags: - engineering - data - api - macro --- Ask a simple question: what are real residential property prices doing in France? FRED has the answer. FRED, in fact, has two answers, and this is where the trouble starts. Two series carry the exact same title, "Real Residential Property Prices for France", and the exact same tags. Same source, same country, same frequency, same seasonal adjustment. As of Q1 2026, one of them reads 99.09. The other reads -0.79. Neither is wrong. The first is an index of the price level (2010 = 100). The second is the growth rate, percent per annum. The only thing that distinguishes them in FRED's own metadata is the units string - and nothing in FRED's search, tags, or API will separate a level from a pace for you. Pick by title and you are flipping a coin, and the losing flip does not look like an error. It returns a perfectly formatted, perfectly plausible, catastrophically wrong number. We call this the France trap, and it is not about France. It is what navigation failure looks like in the best free economic archive on the internet. This post is the anatomy of what we built on top: not a proxy for FRED, but a way to make it navigable. ## A magnificent archive with no card catalog Let us be clear about the object first. FRED, maintained by the Federal Reserve Bank of St. Louis, is a gift: hundreds of thousands of economic time series - our own facet counters sum the inventory at about 845,000 - from dozens of sources, free, stable, versioned, documented. The macro data most dashboards quietly run on comes from here. If you build anything with economic data and do not know FRED, start there tonight. Then try to find something. The interface the archive offers is a text box and a flat sea of tags. Metadata lives in prose: the license terms sit inside a free-text notes field, the revision behavior is folklore, and the difference between a level and a rate of change is - as France just demonstrated - not represented at all. Across the top thousand series by popularity there are 144 distinct unit strings. That is not a taxonomy; that is a pile. None of this is a criticism of FRED. Archives archive. Navigation is a different product, and nobody had built it. ## Eight facets, honest counters The Sugra macro layer starts by compiling FRED's tag sea - 6,025 tags - into exactly eight facet groups: geo, source, frequency, seasonality, geo_type, concept, license, release. ``` GET /api/v1/macro/facets ``` Called with no arguments, it returns the top values of every facet across the full inventory, with counts: 750,006 series are not seasonally adjusted, 95,098 are. Add q= for text and tags= for what you have already chosen, and the facets return what remains - the counts shrink as you narrow, like any decent filter UI, except it is an API and the numbers are real: ``` GET /api/v1/macro/facets ?q=residential property prices &tags=usa -> series_count: 113 GET /api/v1/macro/series ?q=residential property prices &tags=usa -> total: 113 ``` The number you see while narrowing is the number you get when you fetch. Add &exclude=sa and both sides agree again: 74. This sounds like a small thing. It is the entire difference between browsing and guessing. Selection itself is deterministic. The same tags and facets return the same set, every time, with an explicit offset contract for paging - not a relevance-ranked lottery that reshuffles when the index sneezes. And the parameters are validated like they mean it: ``` GET /api/v1/macro/series?geo=bis -> 400 "'bis' is a source, not a geo. Pass it as source= or in tags=." ``` A 400 that names the mistake and the fix. Error messages are interface too. ## The measure field, or how not to fall into the trap Back to France. Here is the same question, asked navigably: ``` GET /api/v1/macro/series ?source=bis &geo=france &concept=real,residential ``` Exactly two rows come back, and they no longer look identical: ``` QFRR628BIS Index 2010=100 index QFRR368BIS % per Annum growth_pct ``` That third column is measure, and FRED has nothing like it. Every row in the macro layer is classified by what kind of number it is: index, level, money, money_saar, rate_pct, spread_pct, count, growth_pct, share_pct, ratio, price. Want only levels? measure=index. Only paces? measure=growth_pct. The trap disappears as a class, not as a special case - the same two-series ambush exists for China (85.13 against -7.07) and for every other country in the BIS residential property family. Two values in the vocabulary matter more than the eleven above: ambiguous and unclassified. When the units string genuinely does not determine the kind - and in a pile of 144 unit strings, sometimes it does not - we say so instead of guessing. A field that is honest about its limits is worth more than a field that is confidently wrong; that is the whole moral of the France trap, applied to ourselves. ![Two line charts stacked: the same series title, Real Residential Property Prices for France, drawn twice - the index level around 99 on top, the annual growth rate dipping below zero beneath - with units and measure labels telling them apart.](/blog/images/posts/making-fred-navigable/france-trap.jpg) *The France trap, drawn. Same title, same tags; the index says 99.09, the growth rate says -0.79. Data: Sugra API - one request each, nothing else: GET /api/v1/fred/series/QFRR628BIS.* ## Licenses, lifted out of prose Some FRED series carry obligations - BIS data is copyrighted and requires citation, with the required wording buried in the notes field as prose. The single-series endpoint returns the obligation as data: ``` GET /api/v1/fred/series/QCNR628BIS "license": { "copyright": "copyrighted", "status": "citation_required", "originator": "bis", "citation": "Sources: National sources, BIS Residential Property Price database, ..." } ``` The citation string is extracted verbatim from the source's own notes - the exact words BIS asks for, not our paraphrase - and the response envelope carries a ready-to-print attribution line. Compliance becomes a field you render, not a legal scavenger hunt. The same endpoint reports meta.data_time as the source's own last revision timestamp, so freshness is a fact you read rather than infer. ## When is the next CPI FRED's release calendar knows every answer and volunteers none: by default it looks backward, and it speaks in numeric release ids. Finding "the next CPI date" means discovering that CPI is release_id 10, then wrestling parameters until yesterday stops being the default. ``` GET /api/v1/macro/releases ?release=cpi&limit=1 -> 2026-08-12 Consumer Price Index ``` Forward by default, with 23 named aliases for the releases people actually ask about - release=cpi, release=nfp, release=fomc, release=gdp - on top of a catalog of all 330. This week alone: the employment report on August 7, CPI on August 12, GDP on August 26. One parameter each. ![Comparison table with eight rows: navigation, selection, level versus pace, licenses, required citations, release calendar, freshness, and errors - the FRED API column against the Sugra column.](/blog/images/posts/making-fred-navigable/the-difference.jpg) *Eight rows, each one a checkable fact, not an adjective.* ## Four recipes Everything above composes, because everything lives under one key and one response envelope. Four patterns we use ourselves: **1. From question to numbers, no guessing.** Narrow with facets, select with series, fetch with the single-series endpoint - three calls, and the third one hands you observations, freshness, and the license in one payload: ``` /api/v1/macro/facets?q=... /api/v1/macro/series?...&measure=index /api/v1/fred/series/{series_id} ``` **2. An event, the market, the news.** Take the CPI date from the calendar, pull a market window around it, and search the news flow - three surfaces, one key, one envelope shape: ``` /api/v1/macro/releases?release=cpi /api/v2/market/chart/SPY?range=3mo /api/v1/news/search?q=inflation ``` **3. The curated shortcut.** When you want the classic indicator rather than the open archive, the curated catalog - 450 hand-checked series with typed units and ready transforms - answers directly: ``` GET /api/v1/macro/us/cpi ?transform=yoy_pct&last_n=12 ``` Twelve months of year-over-year CPI, computed server-side. Facets are for exploring the open sea; the catalog is the marked harbor. The in_catalog flag on every series row tells you when the open archive and the curated layer meet. ![Line chart of US CPI year over year across the last five years: the June 2022 peak at 8.98 percent, the long descent, and the latest reading at 3.46 percent, with the 2 percent line dashed.](/blog/images/posts/making-fred-navigable/cpi-yoy.jpg) *Recipe 3, drawn: five years of US CPI, year over year, straight off the curated catalog. Data: Sugra API - one request, nothing else: GET /api/v1/macro/us/cpi?transform=yoy_pct&last_n=60.* **4. One query, any country.** The BIS residential property family answers the France question for dozens of countries with the same two-line query - swap geo=france for geo=australia, geo=chile, geo=greece, and nothing else changes. Comparative charts stop being a scraping project and start being a loop. ![Four lines leave the 100 mark in 2010 and diverge: the United States climbs to 156, Germany to 128, Japan to 121, and Greece sinks to 97, still below its 2010 level.](/blog/images/posts/making-fred-navigable/four-countries.jpg) *Recipe 4, drawn: the same two-line query, four values of geo=. Sixteen years on, the United States sits 56% above its 2010 level in real terms; Greece is still 3% below it. Data: Sugra API - GET /api/v1/macro/series?source=bis&geo=...&concept=real,residential, then one GET per series id.* ## The deeper drawers The eight facets are the front of the cabinet, not the end of it. A few drawers behind them, each one call: ``` GET /api/v1/macro/multi ?series=us/cpi,us/unemployment ``` Several curated indicators in one request, one envelope - the dashboard call. ``` GET /api/v1/fred/regional?symbol=CAUR ``` FRED's regional families, reachable by state-level series id - California unemployment here, any state the same way. ``` GET /api/v1/fred/corporate/hqm GET /api/v1/fred/government/tips?tenor=10 ``` A 200-point corporate bond spot curve in one response, and real yields by tenor from inflation-protected securities. ``` GET /api/v1/macro/country-profile ?country=de ``` A one-call country dossier. And past FRED entirely, the same envelope keeps going into IMF vintages and revisions, central bank balance sheet history, and trade direction - that wider tour lives in [the Sugra Macro launch post](/blog/sugra-macro), including why revisions matter: a stale forecast looks exactly like a fresh one. ## Or just ask an agent Every endpoint above is also exposed through Sugra API MCP - the same gateway, spoken natively by agents. Point any MCP-capable assistant at the hosted server (`mcp.sugra.ai/mcp`, your API key) or install the connector from PyPI, and "what are real residential property prices doing in France, chart them" becomes a conversation: the agent narrows with facets, reads measure instead of flipping the title coin, pulls both series, and draws the chart - trap sidestepped, citation attached, and you never told it a series id. That is the quiet payoff of navigation as an API: it is not just easier for people. It is the difference between an agent that can use an archive and an agent that can only search one. ## What this is not We do not proxy FRED wholesale, and we do not improve on its data - nobody improves on the St. Louis Fed's archive. The observations are theirs, revision stamps and all, and the required citations travel with every response. What we built is the missing card catalog: facets over tags, a measure field over unit-string archaeology, licenses over prose, a calendar that faces forward. The archive stays magnificent. It just stops being a maze. Everything in this post runs on the free tier - 50 requests a day, every endpoint, no feature gates. [Get a key](https://app.sugra.ai/register), run the France query, and watch two identical titles turn into two different, correctly labeled answers. ## Reading - [FRED](https://fred.stlouisfed.org/) - the archive itself. Eight hundred thousand reasons it deserves better navigation. - [FRED API documentation](https://fred.stlouisfed.org/docs/api/fred/) - the raw surface all of this is built over. - [BIS residential property price statistics](https://www.bis.org/statistics/pp.htm) - the family behind the France trap, and the citation your dashboard owes them. - [Sugra API reference](https://sugra.ai/docs) - every route in this post, with the facet flow documented in the descriptions. - [sugra-api-mcp on PyPI](https://pypi.org/project/sugra-api-mcp/) - the connector, if your client runs local.