https://github.com/hoenn/go-hn
A Go wrapper for the HackerNews API
https://github.com/hoenn/go-hn
api-client go golang hackernews hackernews-api
Last synced: 3 months ago
JSON representation
A Go wrapper for the HackerNews API
- Host: GitHub
- URL: https://github.com/hoenn/go-hn
- Owner: hoenn
- License: mit
- Created: 2019-05-03T19:57:07.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2022-06-21T16:56:47.000Z (almost 4 years ago)
- Last Synced: 2025-08-15T09:47:48.657Z (8 months ago)
- Topics: api-client, go, golang, hackernews, hackernews-api
- Language: Go
- Homepage:
- Size: 47.9 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://goreportcard.com/report/github.com/hoenn/go-hn)
[](https://pkg.go.dev/github.com/hoenn/go-hn)
## go-hn
`go` wrapper for the HackerNews Firebase API.
### Getting started
Add this package to your `go` path.
`go get github.com/hoenn/go-hn`
then create the client with
```go
import "github.com/hoenn/go-hn/pkg/hnapi"
//...
c := hnapi.NewHNClient()
```
### Concepts
Stories, comments, jobs, asks and polls are all "items". `Item` contains a superset of the properties in each subtype. Helpers like `GetComment` can help reduce Item into a more specific Comment type.
#### Items
##### Item
Field | Type | Description
------|------|------------
By | `string` | The username of the story's author
Delete | `bool` | If this item has been deleted
Dead | `bool` | If this item has been marked Dead
ID | `int` | This story's item id
Descendants | `int` | The total comment count
Kids | `[]int` | The ids of the story's comments, in ranked display order.
Score | `int` | The story's score
Time | `int64` | Creation date of the story in Unix Time
Timestamp | `time.Time` | Creation date of the item
Title | `string` | The story's title
URL | `string` | The URL of the story
Type | `string` | The type of item ("story")
Poll | `int` | Associated Poll
Parts | `int` | Associated Poll Options
##### Story
Field | Type | Description
------|------|------------
By | `string` | The username of the story's author
ID | `int` | This story's item id
Descendants | `int` | The total comment count
Kids | `[]int` | The ids of the story's comments, in ranked display order.
Score | `int` | The story's score
Time | `int64` | Creation date of the story in Unix Time
Timestamp | `time.Time` | Creation date of the story
Title | `string` | The story's title
URL | `string` | The URL of the story
Type | `string` | The type of item ("story")
##### Comment
Field | Type | Description
------|------|------------
By | `string` | The username of the comments's author
ID | `int` | This comments's item id
Kids | `[]int` | The ids of the story's comments, in ranked display order.
Parent | `int` | The comment's parent (another comment or the original story)
Time | `int64` | Creation date of the comment in Unix Time
Timestamp | `time.Time` | Creation date of the comment
Text | `string` | The comment's text
Type | `string` | The type of item ("comment")
##### Poll
Field | Type | Description
------|------|------------
By | `string` | The username of the Poll's author
ID | `int` | This poll's item id
Descendants | `int` | The total comment count
Kids | `[]int` | The ids of the poll's comments, in ranked display order.
Score | `int` | The poll's score
Time | `int64` | Creation date of the poll in Unix Time
Timestamp | `time.Time` | Creation date of the poll
Title | `string` | The poll's title
URL | `string` | The URL of the poll
Type | `string` | The type of item ("poll")
Parts | `[]int` | The item ids of the poll options
##### PollOpt
Field | Type | Description
------|------|------------
By | `string` | The username of the pollopt's author
ID | `int` | This pollopt's item id
Poll | `int` | The pollopt's parent (the poll it belongs to)
Time | `int64` | Creation date of the pollopt in Unix Time
Timestamp | `time.Time` | Creation date of the pollopt
Text | `string` | The pollopt's text
Type | `string` | The type of item ("pollopt")
#### Users
Users are identified by case-sensitive ids. Only users that have public activity (comments or story submissions) on the site are available through the API.
##### HNUser
Field | Type | Description
------|------|------------
About | `string` | The user's 'about' info (HTML)
Created | `int64` | Creation date of the user in Unix Time
Delay | `int` | Delay in minutes between comments becoming visible after posting
ID | `string` | The user's unique username, case-sensitive
Karma | `int` | The user's karma
Submitted | `[]int` | List of all item submissions by user
#### Additional Functionality
##### Top Stories
There are additional functions in the `hnapi` package for getting the "Top" stories by type as determined by the API itself. You can call `client.TopStoryIDs` passing one of the following `TopType`:
```go
// Top is for the top ~500 stories.
Top TopType = "topstories"
// New is for the new stories.
New TopType = "newstories"
// Best is for the highest ranking stories.
Best TopType = "beststories"
// Show is for stories categorized as 'Show'.
Show TopType = "showstories"
// Job is for stories categorized as 'Jobs'.
Job TopType = "jobstories"
```
Any of the `TopType` options will return up to ~500 item ids.
##### Updates
The HackerNews API also exposes an endpoint to poll for updates. `client.Updates` will return a single `*Update` containing
Field | Type | Description
------|------|------------
Items | `[]int` | Items that have been recently updated
Profiles | `[]string` | User profiles that have been recently updated
### Example Usage
```go
package main
import (
"fmt"
"github.com/hoenn/go-hn/pkg/hnapi"
)
func main() {
// Create client.
c := hnapi.NewHNClient()
// Display a specific user's karma.
user, err := c.User("someuser")
if err != nil {
panic(err)
}
fmt.Println(user.Karma)
// Get the current max item id.
maxID, err := c.MaxItemID()
if err != nil {
panic(err)
}
// Get the details of the current max item.
maxItem, err := c.GetItem(maxID)
// ...
id := 478932 // Some comment ID.
comment, err := c.GetComment(id)
fmt.Println(comment.By)
// ...
}
```
### CLI
The repository also contains `go-hn-cli` which may be useful. To use it:
```
# Navigate to the package.
cd cmd/go-hn-cli
# Create binary in directory.
go build
./go-hn-cli GetItem -i 8373
# Install binary to path.
go install
go-hn-cli GetItem -i 8373
# Without building or installing.
go run main.go GetItem -i 8373
```