Alexander Beletsky
Alexander Beletsky

Reputation: 19831

GitHub API - stars, get the date then star is created

The GitHub API provides functionality to get stared items sorted by created date. But, I can't find a possibility to get this date.

Only three date-type fields are present in the response:

created_at: '2013-06-13T21:10:36Z',
updated_at: '2013-06-18T07:45:56Z',
pushed_at: '2013-06-17T16:52:44Z',

create_at here is always that date the repository created, not star. updated_at does not give the right information either.

On the GitHub site, if you check your stars, data is sorted properly and the correct time span is rendered. But it looks like the API misses that information.

That gist clearly show, that data returned "sorted", but created_at is wrong.

Upvotes: 21

Views: 2236

Answers (3)

mikyll98
mikyll98

Reputation: 2283

Short Answer

You need to use the "List stargazers" REST API and add the header "Accept: application/vnd.github.star+json" to the request.

curl -L -s \
  -H "Accept: application/vnd.github.star+json" \
  https://api.github.com/repos/{owner}/{repo}/stargazers

Docs Reference

From GitHub Docs: REST APIs - List stargazers

Lists the people that have starred the repository.

This endpoint supports the following custom media types. For more information, see "Media types."

  • application/vnd.github.star+json: Includes a timestamp of when the star was created.

Example (Single Page)

Here's a quick example without an access token:

curl -L -s \
  -H "Accept: application/vnd.github.star+json" \
  https://api.github.com/repos/mikyll/SDL2-Controller-Tester/stargazers

This command retrieves the stars (up to 100) of the first page of the repository mikyll/SDL2-Controller-Tester.

If you hit the GitHub API rate limit, you can add a personal access token to the request with the authorization header (-H "Authorization: token <gh_token>").

To manage access tokens you can access this page.

Example (Multiple Pages)

List stargazers API retrieves stars based on their page number, and you can use query parameters to customize that:

  • page sets the page number of the results to fetch (default 1);
  • per_page sets the number of results per page (max 100);

When addressing repositories with a high number of stars, to get the full star history you have to send multiple requests.

The following Bash script loops over all the pages (each valid response contains a header with the link to the next page) and saves a simpler JSON in a file star_history.json:

#!/bin/bash

# GitHub repository details
OWNER="owner_name"
REPO="repository_name"

# GitHub personal access token for authentication (it provides higher rate limit)
TOKEN="github_token"

# Base URL for the GitHub API
URL="https://api.github.com/repos/${OWNER}/${REPO}/stargazers"

# Custom accept header to include starred_at timestamp
ACCEPT_HEADER="Accept: application/vnd.github.star+json"

# Authentication header (uncomment if using a token)
# AUTH_HEADER="Authorization: token ${TOKEN}"

# Initial page
PAGE=1

# Max results per page
PER_PAGE=100

# Loop through all pages of results
while true
do
  # Make request to GitHub API
  RESPONSE=$(curl -s -H "${ACCEPT_HEADER}" -H "${AUTH_HEADER}" "${URL}?page=${PAGE}&per_page=${PER_PAGE}")

  # Check if the response is empty
  if [ -z "${RESPONSE}" ] || [ "${RESPONSE}" == "[]" ] || [[ "${RESPONSE}" != *"starred_at"* ]]
  then
    break
  fi

  # Check if rate limit was hit
  if [[ "${RESPONSE}" == *"API rate limit exceeded"* ]]
  then
    break
  else
    # Process the response
    echo "${RESPONSE}"
    
    # Increment the page number
    ((PAGE++))
  fi
done | jq '[ .[] | { "username": .user.login, "timestamp": .starred_at } ]' > star_history.json

Upvotes: 1

timqian
timqian

Reputation: 3396

This can be done in the GitHub API v3 by adding the header:

Accept: application/vnd.github.v3.star+json

see here:

https://developer.github.com/v3/activity/starring/#alternative-response-with-star-creation-timestamps-1

https://developer.github.com/v3/activity/starring/#alternative-response-with-star-creation-timestamps

Upvotes: 16

Ian Stapleton Cordasco
Ian Stapleton Cordasco

Reputation: 28807

There is absolutely no way to get this information from the API. Your best chance of getting it is going through events either on the repository or each user that has starred the repository and that could take tons of parsing because the events could be in the thousands. The number of API calls to do so would be immense.

Upvotes: 1

Related Questions