News Service API Documentation¶

Subscription Required

A subscription is required to use SQWARE Terminal services, including the APIs and real-time data feeds described. API keys and management can be found on your account page.

This document provides details for interacting with the News Service API, which allows users to fetch news articles, search for specific news, and receive real-time updates.

Base URL¶

The API is hosted at https://news.sqware.pro/. All endpoint paths are relative to this base URL.

Authentication¶

Currently, the API does not implement any authentication. All endpoints are publicly accessible.

API Endpoints¶

1. Search News Articles¶

This is the primary endpoint for searching and filtering news articles.

Endpoint: GET /api/news
Method: GET
Description: Retrieves a list of news articles based on specified search criteria and filters.

Query Parameters:

Parameter	Type	Default	Required	Description	Example
`query`	string	`null`	No	A search term to match against article titles and descriptions (full-text).	`tech earnings`
`tickers`	string	`null`	No	A comma-separated list of stock tickers to filter articles by.	`AAPL,MSFT,GOOG`
`tags`	string	`null`	No	A comma-separated list of tags to filter articles by.	`ai,ipo,crypto`
`limit`	integer	`50`	No	The maximum number of articles to return.	`25`
`offset`	integer	`0`	No	The number of articles to skip (for pagination).	`50`

Example Request:

GET /api/news?query=renewable%20energy&tickers=TSLA&limit=10
Success Response (200 OK):
- Content-Type: application/json
- Body:
```
{
  "results": [
    {
      "id": 123,
      "title": "Global Shift Towards Renewable Energy Accelerates",
      "description": "A new report indicates a significant increase in investments...",
      "url": "https://example.com/news/renewable-energy-shift",
      "published_date": "2023-10-26T10:00:00Z",
      "crawl_date": "2023-10-26T10:05:00Z",
      "is_breaking": false,
      "source": "example.com",
      "tickers": ["TSLA", "NEE"],
      "tags": ["renewable", "energy", "investment"]
    }
    // ... more articles
  ],
  "count": 1 
}
```
- Article Object Properties:
  - id (integer): Unique identifier for the article in the database.
  - title (string): The headline of the news article.
  - description (string): A summary or short description of the article.
  - url (string): The direct URL to the original news article.
  - published_date (string, ISO 8601 format): The original publication date and time of the article.
  - crawl_date (string, ISO 8601 format): The date and time when the article was fetched by the service.
  - is_breaking (boolean): Indicates if the article is marked as breaking news.
  - source (string): The domain name of the news source.
  - tickers (array of strings): A list of stock tickers associated with the article.
  - tags (array of strings): A list of tags or keywords associated with the article.
Error Responses:
- 422 Unprocessable Entity: If query parameters are invalid (e.g., limit is not an integer).
- 500 Internal Server Error: If an unexpected error occurs on the server.

2. Get Latest Breaking News¶

Retrieves the most recent breaking news articles.

Endpoint: GET /api/breaking-news
Method: GET
Description: Fetches a list of the latest articles marked as breaking news.
Query Parameters:

Parameter Type Default Required Description

limit integer 10 No The maximum number of articles to return.
Example Request:

GET /api/breaking-news?limit=5
Success Response (200 OK):
- Content-Type: application/json
- Body: Same structure as /api/news response ({"results": [...], "count": ...}).

3. Get Latest News Articles¶

Retrieves the most recently crawled news articles, regardless of whether they are breaking news.

Endpoint: GET /api/latest-news
Method: GET
Description: Fetches a list of the most recently added articles to the system.
Query Parameters:

Parameter Type Default Required Description

limit integer 100 No The maximum number of articles to return.
Example Request:

GET /api/latest-news?limit=20
Success Response (200 OK):
- Content-Type: application/json
- Body: Same structure as /api/news response ({"results": [...], "count": ...}).

4. Get News Sources¶

Lists all the configured news sources from which the service fetches articles.

Endpoint: GET /api/sources
Method: GET
Description: Returns a list of available news source names.
Query Parameters: None.
Example Request:

GET /api/sources

Success Response (200 OK):

Content-Type: application/json

Body:

{
  "sources": [
    { "name": "SourceA_RSS" },
    { "name": "SourceB_API" }
    // ... more sources
  ],
  "count": 2
}

Source Object Properties:
- name (string): The identifier/name of the news source.

WebSocket API¶

The service also provides a WebSocket endpoint for real-time updates.

Endpoint: GET /ws
Description: Establishes a WebSocket connection for receiving real-time news updates.

Connection¶

Clients can connect to ws://<host>:<port>/ws.

Server-to-Client Messages¶

Once connected, the server will send messages in JSON format. Each message has a type field indicating the nature of the update and a data field containing the payload.

Initial Latest News:
- Sent immediately after a successful connection.
- Type: initial_latest_news
- Data: An array of latest article objects (same structure as in GET /api/news results).
- Example:
```
{
  "type": "initial_latest_news",
  "data": [ /* array of article objects */ ]
}
```
Initial Breaking News:
- Sent immediately after a successful connection if breaking news is available.
- Type: initial_breaking_news
- Data: An array of breaking news article objects.
- Example:
```
{
  "type": "initial_breaking_news",
  "data": [ /* array of article objects */ ]
}
```
New Articles:
- Sent when new articles are fetched and stored by the system.
- Type: new_articles
- Data: An array of newly added article objects.
- Example:
```
{
  "type": "new_articles",
  "data": [ /* array of new article objects */ ]
}
```
Breaking News Update:
- Sent when there's an update to breaking news (e.g., new breaking news identified).
- Type: breaking_news
- Data: An array of current breaking news article objects.
- Example:
```
{
  "type": "breaking_news",
  "data": [ /* array of breaking news article objects */ ]
}
```

Client-to-Server Messages¶

Clients can send messages to the WebSocket server, primarily for performing searches.

Search Request:

Allows the client to request a search over WebSocket.

Message Format (JSON):

{
  "type": "search",
  "query": "optional search string",
  "tickers": ["optional", "list", "of", "tickers"],
  "tags": ["optional", "list", "of", "tags"],
  "limit": 50, // optional, default 50
  "offset": 0, // optional, default 0
  "request_id": "client_generated_id" // optional, for matching response
}

query, tickers, tags, limit, offset correspond to the parameters of the GET /api/news endpoint.
tickers and tags should be provided as arrays of strings.
request_id is an optional field that the client can use to correlate responses with requests.

Search Results (Server Response to Search Request):
- Sent by the server in response to a search message from the client.
- Type: search_results
- Data: An array of article objects matching the search criteria.
- request_id (optional): If the client provided a request_id in the search message, it will be echoed back here.
- Example:
```
{
  "type": "search_results",
  "request_id": "client_generated_id_123", 
  "data": [ /* array of article objects */ ]
}
```

Rate Limiting¶

The API does not currently implement explicit rate limiting. Please use the API responsibly.

Error Handling¶

Standard HTTP status codes are used for REST API errors (e.g., 404 Not Found, 422 Unprocessable Entity, 500 Internal Server Error).

Error responses will typically be in JSON format, though the specific structure for all errors is not detailed here.

// Example for 422 Unprocessable Entity (FastAPI default)
{
    "detail": [
        {
            "loc": ["query", "limit"],
            "msg": "value is not a valid integer",
            "type": "type_error.integer"
        }
    ]
}

Future Considerations¶

Authentication (e.g., API Keys)
More detailed error response objects.
Explicit Rate Limiting.
Versioning.