Skip to content

Commit 563cf01

Browse files
committed
docs(api-server): add explanation for 'usage' filter in country model
- Include an Aside component to explain the purpose and benefits of using the 'usage' filter for country data retrieval - Emphasize how this filter enhances user experience and optimizes data display by providing relevant country options - Illustrate examples of filtering 'event countries' in headlines and 'headquarters' of sources
1 parent a27ae26 commit 563cf01

File tree

1 file changed

+6
-0
lines changed

1 file changed

+6
-0
lines changed

src/content/docs/api-server/features/data-management-api.mdx

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,12 @@ GET /api/v1/data?model=country&filter={"usage":"eventCountry"}
2929
```
3030
This fetches countries that are referenced as 'event countries' in headlines. Similarly, `filter={"usage":"headquarters"}` can be used to fetch countries that are headquarters for sources.
3131

32+
<Aside type="note" title="Why use the 'usage' filter for countries?">
33+
The `usage` filter for the `country` model is designed to enhance the client-side user experience and optimize data retrieval. Instead of fetching a comprehensive list of all countries globally, this filter allows client applications to retrieve only those countries that are *relevant* to existing content.
34+
35+
For instance, when a user wants to filter headlines by the country where the news event occurred, it's often more practical to present a list of countries for which actual headlines exist. Similarly, when filtering by the headquarters of news sources, displaying only countries that host active sources provides a more focused and actionable selection. This approach avoids presenting users with a long list of irrelevant options, streamlining navigation and improving the efficiency of data display.
36+
</Aside>
37+
3238
### The Dual Registry System
3339

3440
The power behind this generic endpoint comes from two central registries:

0 commit comments

Comments
 (0)