SEC API: Choosing Between Metadata Query and Full-Text Search

When building an application that uses SEC filing data, there are two main ways to find the documents you need: searching by metadata or using a full-text search. Each method answers a different kind of question. Choosing the correct one will make your application more efficient and your results more accurate.

A metadata query is like looking for a book in a library catalog using its title or author. A full-text search is like searching every word on every page of every book in the library. This guide explains the difference between these two approaches and provides clear use cases for each.

The Metadata Query (/v1/filings)

A metadata query searches the structured, high-level information about a filing. This data includes fields like:

• CIK (Central Index Key): The unique ID for each company.

• Form Type: The type of filing (e.g., 10-K, 8-K, Form 4).

• Filing Date: When the document was submitted to the SEC.

• Item Numbers: For forms like the 8-K, the specific event types being reported.

This type of query is fast and direct because it works with indexed, predictable data fields.

When to Use a Metadata Query:

You should use a metadata query when your question is about the "who, what, or when" of a filing.

• Use Case 1: Finding all filings for a specific company.

  • Question: "Give me every filing from Apple Inc."

  • Method: Query the /v1/filings endpoint with cik=320193.

• Use Case 2: Monitoring for specific report types.

  • Question: "Show me all 10-K annual reports filed last month."

  • Method: Query with form_type=10-K and the desired date range.

• Use Case 3: Detecting specific corporate events.

  • Question: "Find all 8-K filings that report an executive departure."

  • Method: Query with form_type=8-K and items_contain=5.02.

In short, if you can define what you are looking for using structured information, the metadata query is the correct tool.

The Full-Text Search (/v1/full-text)

A full-text search looks inside the documents themselves. It scans the entire text of each filing to find mentions of a specific word or phrase. This method is more computationally intensive but allows you to find information that is not available in the metadata.

When to Use a Full-Text Search:

You should use a full-text search when your question is about the topics being discussed inside the filings.

• Use Case 1: Tracking a market or technology trend.

  • Question: "How many 10-K filings mentioned 'artificial intelligence' this year compared to last year?"

  • Method: Query the /v1/full-text endpoint with text_contains="artificial intelligence" for each year.

• Use Case 2: Finding information on a non-standard topic.

  • Question: "Which companies are discussing 'supply chain disruptions' in their risk factors?"

  • Method: Query with text_contains="supply chain disruptions".

• Use Case 3: Discovering filings related to a specific product or legal case.

  • Question: "Find any filings that mention the 'Acme Corporation lawsuit'."

  • Method: Query with text_contains="Acme Corporation lawsuit".

Use full-text search when your query is based on the narrative content of the documents.

Quick Comparison

Final Thoughts

Choosing the right search method is a key step in designing an efficient application.

• Use a metadata query for precise lookups based on known information.

• Use a full-text search for discovery and analysis based on the content of the filings.

By selecting the correct tool for the job, you can get the exact data you need with better performance and lower API usage.