HN Search API

https://hn.algolia.com/api
Admin
HN Search API is a REST API built on Algolia Search that enables developers to programmatically...
Tokens:3,768
Snippets:22
Trust Score:10
Update:6 days ago
Show doc for...
Tokens:
Raw
### Search examples

Source: https://hn.algolia.com/api

Example queries demonstrating various search filters and parameters.

```http
http://hn.algolia.com/api/v1/search?query=foo&tags=story
```

```http
http://hn.algolia.com/api/v1/search?query=bar&tags=comment
```

```http
http://hn.algolia.com/api/v1/search?query=bar&restrictSearchableAttributes=url
```

```http
http://hn.algolia.com/api/v1/search?tags=front_page
```

```http
http://hn.algolia.com/api/v1/search_by_date?tags=story
```

```http
http://hn.algolia.com/api/v1/search_by_date?tags=(story,poll)
```

```http
http://hn.algolia.com/api/v1/search_by_date?tags=comment&numericFilters=created_at_i>X
```

```http
http://hn.algolia.com/api/v1/search_by_date?tags=story&numericFilters=created_at_i>X,created_at_i<Y
```

```http
http://hn.algolia.com/api/v1/search?tags=story,author_pg
```

```http
http://hn.algolia.com/api/v1/search?tags=comment,story_X
```

--------------------------------

### User response example

Source: https://hn.algolia.com/api

Example JSON response for a user request.

```json
{
  * username: "pg",
  * about: "PG's bio",
  * karma: 99999

}
```

--------------------------------

### Item response example

Source: https://hn.algolia.com/api

Example JSON response for an item request, showing nested children structure.

```json
{
  * id: 1,
  * created_at: "2006-10-09T18:21:51.000Z",
  * author: "pg",
  * title: "Y Combinator",
  * url: "http://ycombinator.com",
  * text: null,
  * points: 57,
  * parent_id: null,
  * children: 
[
    * {
      * id: 15,
      * created_at: "2006-10-09T19:51:01.000Z",
      * author: "sama",
      * text: "&#34;the rising star of venture capital&#34; -unknown VC eating lunch on SHR",
      * points: 5,
      * parent_id: 1,
      * children: 
[
        * {
          * id: 17,
          * created_at: "2006-10-09T19:52:45.000Z",
          * author: "pg",
          * text: "Is there anywhere to eat on Sandhill Road?",
          * points: 5,
          * parent_id: 15,
          * children: [ ]
}
]
}
]

}
```

--------------------------------

### Search response example

Source: https://hn.algolia.com/api

Example JSON response for a search query, showing hits, pagination, and highlighting.

```json
{
  * hits:
[
    * {
      * title: "Y Combinator",
      * url: "http://ycombinator.com",
      * author: "pg",
      * points: 57,
      * story_text: null,
      * comment_text: null,
      * _tags: 
[
        * "story"
],
      * num_comments: 2,
      * objectID: "1",
      * _highlightResult: 
{
        * title: 
{
          * value: "Y Combinator",
          * matchLevel: "none",
          * matchedWords: [ ]
},
        * url: 
{
          * value: "http://ycombinator.com",
          * matchLevel: "none",
          * matchedWords: [ ]
},
        * author: 
{
          * value: "<em>pg</em>",
          * matchLevel: "full",
          * matchedWords: 
[
            * "pg"
]
}
}
}, [...]
],
  * page: 0,
  * nbHits: 11,
  * nbPages: 1,
  * hitsPerPage: 20,
  * processingTimeMS: 1,
  * query: "pg",
  * params: "query=pg"

}
```

--------------------------------

### GET user by username

Source: https://hn.algolia.com/api

Retrieves a user's public profile by username. The response includes username, about, and karma.

```http
GET`http://hn.algolia.com/api/v1/users/:username`
```

--------------------------------

### GET item by ID

Source: https://hn.algolia.com/api

Retrieves a single item (story, comment, etc.) by its ID. The response includes fields such as id, created_at, author, title, url, text, points, parent_id, and nested children.

```http
GET`http://hn.algolia.com/api/v1/items/:id`
```

--------------------------------

### GET /api/v1/users/:username

Source: https://hn.algolia.com/api

Retrieves profile information for a specified Hacker News user, including their about text and karma.

```APIDOC
## GET /api/v1/users/:username

### Description
Fetches profile information for a Hacker News user by their username.

### Method
GET

### Endpoint
http://hn.algolia.com/api/v1/users/:username

### Parameters
#### Path Parameters
- **username** (string) - Required - The user's username.

### Response
#### Success Response (200)
- **username** (string) - The user's username.
- **about** (string) - The user's bio or about text.
- **karma** (integer) - The user's karma score.

#### Response Example
{
  "username": "pg",
  "about": "PG's bio",
  "karma": 99999
}

```

--------------------------------

### GET /api/v1/search_by_date

Source: https://hn.algolia.com/api

Performs a full-text search across Hacker News items, sorted by date (most recent first). Supports the same query parameters as the /search endpoint.

```APIDOC
## GET /api/v1/search_by_date

### Description
Performs a search across Hacker News items, sorted by date (more recent first). Supports the same query parameters as the /search endpoint.

### Method
GET

### Endpoint
http://hn.algolia.com/api/v1/search_by_date

### Parameters
#### Query Parameters
- **query** (string) - Optional - Full-text search query.
- **tags** (string) - Optional - Comma-separated list of filters. Available tags: story, comment, poll, pollopt, show_hn, ask_hn, front_page, author_:USERNAME, story_:ID. Tags are ANDed by default, can be ORed if within parentheses.
- **numericFilters** (string) - Optional - Comma-separated list of numeric filters using operators (<, <=, =, >, >=). Available fields: created_at_i, points, num_comments.
- **page** (integer) - Optional - Page number for paginated results.
- **hitsPerPage** (integer) - Optional - Number of hits per page.

### Response
#### Success Response (200)
- **hits** (array) - Array of matching items.
- **page** (integer) - Current page number.
- **nbHits** (integer) - Total number of hits.
- **nbPages** (integer) - Total number of pages.
- **hitsPerPage** (integer) - Number of hits per page.
- **processingTimeMS** (integer) - Processing time in milliseconds.
- **query** (string) - The search query.
- **params** (string) - The search parameters used.

#### Response Example
Similar to the /search response, with hits sorted by date.

```

--------------------------------

### GET /api/v1/items/:id

Source: https://hn.algolia.com/api

Retrieves a single Hacker News item by its ID, including nested comments and children items.

```APIDOC
## GET /api/v1/items/:id

### Description
Fetches a Hacker News item (story, comment, poll, etc.) by its unique ID.

### Method
GET

### Endpoint
http://hn.algolia.com/api/v1/items/:id

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique ID of the item.

### Response
#### Success Response (200)
- **id** (integer) - The item's unique ID.
- **created_at** (string) - The creation date in ISO 8601 format.
- **author** (string) - The author's username.
- **title** (string) - The title of the item.
- **url** (string) - The URL of the item.
- **text** (string) - The text content (if any).
- **points** (integer) - The number of points.
- **parent_id** (integer) - The parent item ID, or null for top-level items.
- **children** (array) - An array of child items.

#### Response Example
{
  "id": 1,
  "created_at": "2006-10-09T18:21:51.000Z",
  "author": "pg",
  "title": "Y Combinator",
  "url": "http://ycombinator.com",
  "text": null,
  "points": 57,
  "parent_id": null,
  "children": [
    {
      "id": 15,
      "created_at": "2006-10-09T19:51:01.000Z",
      "author": "sama",
      "text": "\"the rising star of venture capital\" -unknown VC eating lunch on SHR",
      "points": 5,
      "parent_id": 1,
      "children": [
        {
          "id": 17,
          "created_at": "2006-10-09T19:52:45.000Z",
          "author": "pg",
          "text": "Is there anywhere to eat on Sandhill Road?",
          "points": 5,
          "parent_id": 15,
          "children": []
        }
      ]
    }
  ]
}

```

--------------------------------

### GET /api/v1/search

Source: https://hn.algolia.com/api

Performs a full-text search across Hacker News items, sorted by relevance, points, and number of comments. Supports filtering by tags, numeric filters, pagination, and restricting searchable attributes.

```APIDOC
## GET /api/v1/search

### Description
Performs a search across Hacker News items using full-text and filter parameters. Results are sorted by relevance, then points, then number of comments.

### Method
GET

### Endpoint
http://hn.algolia.com/api/v1/search

### Parameters
#### Query Parameters
- **query** (string) - Optional - Full-text search query.
- **tags** (string) - Optional - Comma-separated list of filters. Available tags: story, comment, poll, pollopt, show_hn, ask_hn, front_page, author_:USERNAME, story_:ID. Tags are ANDed by default, can be ORed if within parentheses.
- **numericFilters** (string) - Optional - Comma-separated list of numeric filters using operators (<, <=, =, >, >=). Available fields: created_at_i, points, num_comments.
- **page** (integer) - Optional - Page number for paginated results.
- **hitsPerPage** (integer) - Optional - Number of hits per page.
- **restrictSearchableAttributes** (string) - Optional - Restrict searchable attributes, e.g., url.

### Response
#### Success Response (200)
- **hits** (array) - Array of matching items.
- **page** (integer) - Current page number.
- **nbHits** (integer) - Total number of hits.
- **nbPages** (integer) - Total number of pages.
- **hitsPerPage** (integer) - Number of hits per page.
- **processingTimeMS** (integer) - Processing time in milliseconds.
- **query** (string) - The search query.
- **params** (string) - The search parameters used.
- **hits** array contains objects with fields: title, url, author, points, story_text, comment_text, _tags, num_comments, objectID, _highlightResult.

#### Response Example
{
  "hits": [
    {
      "title": "Y Combinator",
      "url": "http://ycombinator.com",
      "author": "pg",
      "points": 57,
      "story_text": null,
      "comment_text": null,
      "_tags": ["story"],
      "num_comments": 2,
      "objectID": "1",
      "_highlightResult": {
        "title": {
          "value": "Y Combinator",
          "matchLevel": "none",
          "matchedWords": []
        },
        "url": {
          "value": "http://ycombinator.com",
          "matchLevel": "none",
          "matchedWords": []
        },
        "author": {
          "value": "<em>pg</em>",
          "matchLevel": "full",
          "matchedWords": ["pg"]
        }
      }
    }
  ],
  "page": 0,
  "nbHits": 11,
  "nbPages": 1,
  "hitsPerPage": 20,
  "processingTimeMS": 1,
  "query": "pg",
  "params": "query=pg"
}

```

--------------------------------

### Search by date

Source: https://hn.algolia.com/api

Search endpoint sorted by date, more recent first.

```http
GET`http://hn.algolia.com/api/v1/search_by_date?query=...`
```

--------------------------------

### Search by relevance

Source: https://hn.algolia.com/api

Search endpoint sorted by relevance, then points, then number of comments.

```http
GET`http://hn.algolia.com/api/v1/search?query=...`
```
Tokens:
Raw