The useful answer first: FRED's category/related endpoint is used to get the related categories for a category, and a related category is defined as a one-way relation between two categories that is not part of a parent-child hierarchy. If you expect a two-way link or a place in the tree, you are looking at the wrong field. Most categories do not have related categories at all, so an empty result is a normal outcome, not necessarily an error in your request.
For readers who want to recompute rather than accept a conclusion, the work is mostly about separating three things: the request parameters you control, the response format you choose, and the meaning of the relation you receive. The source documentation establishes each of these separately, and the points below stay inside what it states.
What this request does and does not represent
The endpoint returns related categories for a given category. The relation is explicitly one-way between two categories and is not part of a parent-child hierarchy. That distinction matters when you are building a category map: a parent-child edge tells you where a category sits in a tree, while a related edge tells you only that a connection was recorded for retrieval.
The documentation gives category 32073 as an example of the parent-child hierarchy Categories > Regional Data > Federal Reserve Districts > St. That is a hierarchy illustration, not a related-category result. The same source notes that this category uses a related category to link to category I.D., which shows how the two mechanisms coexist for a single category.
Because most categories do not have related categories, a practical habit is to treat an empty related list as evidence about coverage, not as a failure. If you are auditing a category graph, record empties as data points rather than skipping them, since skipped empties will bias any count of how often relations appear.
Parameters you can control
The API key is required and is described as a 32 character alpha-numeric lowercase string. The documentation includes the demonstration value abcdefghijklmnopqrstuvwxyz123456 and states that it is for demonstration purposes only, so it should be treated as a placeholder rather than a credential for production use.
The file_type parameter selects the response type: this request can return either XML or JSON by setting file_type to xml or json. The default value of file_type is xml. If your pipeline parses JSON, an omitted file_type will quietly return the other format, which is one of the most common reasons a working parser appears to break.
There is also a date field described as a YYYY-MM-DD formatted string, optional, with a default of today's date. The source also points to Real-Time Periods for more information. The documentation does not, in the material available here, spell out how that date changes the related-category output, so do not assume it filters categories by creation date.
| Element | Status in source | What to check |
|---|---|---|
| API key | Required; 32 character alpha-numeric lowercase string | Not the demonstration string |
| file_type | xml or json; default xml | Set explicitly if you need JSON |
| Date field | Optional YYYY-MM-DD; default today's date | Confirm before relying on filtering |
| Related category | One-way, not parent-child | Do not merge with hierarchy edges |
A reproducible check order
- Confirm the key format first: 32 character alpha-numeric lowercase string, and never the demonstration key in a real run.
- Set file_type explicitly to json or xml so the format is a decision, not a default.
- Record the category I.D. you queried and the date field value you sent, including when you relied on the default of today's date.
- Log empty related lists as results, since most categories do not have related categories.
- Keep hierarchy and related edges in separate tables so a one-way relation is never read as a tree position.
Hypothetical: if you sample 100 categories and 90 return no related categories, your observed share with at least one relation is 10 percent. That number is a calculation from the hypothetical sample, not a documented coverage rate. It illustrates why an audit must include empties: a list built only from categories that returned relations would report 100 percent coverage by construction.
How to read a returned relation
When a result does appear, the correct interpretation is narrow: a related category is a one-way relation between two categories that is not part of a parent-child hierarchy. The documentation's example category 32073 sits in the hierarchy Categories > Regional Data > Federal Reserve Districts > St. and also uses a related category to link to category I.D. A single category can therefore have both kinds of connectivity, and your data model should allow both without treating one as the other.
For method pages, the safest unit of record is the edge type plus the direction, not a combined adjacency list. If you later compare category structure across datasets, a one-way relation and a hierarchy edge are not interchangeable, and the source does not provide a rule for converting one into the other.
What the source does not say
- It does not establish that related categories are reciprocal; the relation is described as one-way.
- It does not give a coverage rate for related categories, only that most categories do not have them.
- It does not explain how the optional YYYY-MM-DD field alters related-category output.
- It does not define the criteria used to create a related-category link.
- It does not state the full response schema for XML or JSON beyond the file-type choice.
- It does not provide a production API key; the included key is for demonstration purposes only.
The practical takeaway for a reproducible method page is to separate request controls, response format, and relation semantics into distinct columns, then log empty results explicitly. That keeps a one-way related link from being misread as a parent-child position and keeps a default file_type from being mistaken for a deliberate choice.