Skip to main content

​
Git City API

Fetch repository data and generate 3D city visualizations from GitHub commit history.
All Git City endpoints require session authentication. You must be signed in to use these endpoints.

​
Get repository city data

GET /api/git-city?owner={owner}&repo={repo}&branch={branch}
Fetches commit history for a GitHub repository and generates 3D city visualization data. Each day with commits becomes a city block, with height proportional to commit activity.

​
Query parameters

ParameterTypeRequiredDescription
typestringNoRequest type. Use user to list a user’s repositories, or omit for repository analysis. Defaults to repo.
ownerstringConditionalGitHub repository owner. Required when type is repo (default).
repostringConditionalGitHub repository name. Required when type is repo (default).
branchstringNoBranch to analyze. Defaults to main.
usernamestringConditionalGitHub username. Required when type is user.

​
Response (repository data)

{
  "repository": {
    "owner": "octocat",
    "repo": "hello-world",
    "branch": "main",
    "fullName": "octocat/hello-world",
    "url": "https://github.com/octocat/hello-world"
  },
  "city": {
    "blocks": [
      {
        "id": "block-2026-04-01",
        "x": 0,
        "z": 0,
        "height": 2.5,
        "color": "#10b981",
        "type": "building",
        "commitCount": 3,
        "date": "2026-04-01"
      }
    ],
    "dimensions": {
      "width": 10,
      "depth": 10,
      "height": 5
    }
  },
  "stats": {
    "totalCommits": 100,
    "uniqueContributors": 5,
    "stars": 42,
    "forks": 12,
    "watchers": 42,
    "language": "TypeScript",
    "topics": ["api", "bot"],
    "license": "MIT License",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2026-04-07T00:00:00Z",
    "description": "A sample repository"
  },
  "commits": [
    {
      "sha": "abc1234",
      "message": "feat: add new feature",
      "author": "octocat",
      "date": "2026-04-07T04:42:20Z",
      "url": "https://github.com/octocat/hello-world/commit/abc1234..."
    }
  ]
}
FieldTypeDescription
repository.ownerstringRepository owner
repository.repostringRepository name
repository.branchstringBranch analyzed
repository.fullNamestringFull repository name (owner/repo)
repository.urlstringGitHub URL for the repository
city.blocksarrayCity blocks representing daily commit activity
city.blocks[].idstringBlock identifier (format: block-YYYY-MM-DD)
city.blocks[].xnumberX-axis grid position
city.blocks[].znumberZ-axis grid position
city.blocks[].heightnumberBlock height (based on commit count, max 10)
city.blocks[].colorstringHex color code based on commit intensity
city.blocks[].typestringBlock type: building, park, water, or road
city.blocks[].commitCountnumberNumber of commits on that day
city.blocks[].datestringDate for the block (YYYY-MM-DD)
city.dimensions.widthnumberCity grid width
city.dimensions.depthnumberCity grid depth
city.dimensions.heightnumberMaximum block height
stats.totalCommitsnumberTotal commits analyzed (up to 100)
stats.uniqueContributorsnumberNumber of unique commit authors
stats.starsnumberRepository star count
stats.forksnumberRepository fork count
stats.watchersnumberRepository watcher count
stats.languagestringPrimary repository language, or Unknown
stats.topicsarrayRepository topic tags
stats.licensestring | nullRepository license name, or null if none
stats.createdAtstring | nullISO 8601 repository creation date
stats.updatedAtstring | nullISO 8601 repository last update date
stats.descriptionstringRepository description
commitsarrayRecent commits (up to 50)
commits[].shastringShort commit SHA (7 characters)
commits[].messagestringFirst line of the commit message
commits[].authorstringCommit author name
commits[].datestringISO 8601 commit date
commits[].urlstringGitHub URL for the commit

​
Block color mapping

Commits per dayColor
1–2#3b82f6 (blue)
3–5#10b981 (green)
6–10#f59e0b (amber)
11+#ef4444 (red)

​
Errors

CodeDescription
401Unauthorized — valid session required
500Failed to generate git city data. The response includes a details field with the underlying error message.

​
Error response (500)

{
  "error": "Failed to generate git city",
  "details": "Failed to fetch commits: 404"
}
FieldTypeDescription
errorstringError summary
detailsstringUnderlying error message for debugging

​
List user repositories

GET /api/git-city?type=user&username={username}
Returns a list of public GitHub repositories for a user, sorted by last updated.

​
Response

{
  "repos": [
    {
      "id": 123456,
      "name": "hello-world",
      "fullName": "octocat/hello-world",
      "description": "A sample repository",
      "stars": 42,
      "forks": 12,
      "language": "TypeScript",
      "updatedAt": "2026-04-07T00:00:00Z",
      "url": "https://github.com/octocat/hello-world"
    }
  ]
}
FieldTypeDescription
reposarrayList of repositories (up to 30)
repos[].idnumberGitHub repository ID
repos[].namestringRepository name
repos[].fullNamestringFull repository name (owner/repo)
repos[].descriptionstring | nullRepository description
repos[].starsnumberStar count
repos[].forksnumberFork count
repos[].languagestring | nullPrimary language
repos[].updatedAtstringISO 8601 last update timestamp
repos[].urlstringGitHub URL

​
Errors

CodeDescription
400Username required
401Unauthorized — valid session required

​
Analyze repository by URL

POST /api/git-city
Accepts a GitHub repository URL and generates city visualization data. Only GitHub repositories are supported.

​
Request body

FieldTypeRequiredDescription
urlstringYesGitHub repository URL (for example, https://github.com/octocat/hello-world)

​
Response

Returns the same response shape as GET /api/git-city. The branch defaults to main.

​
Errors

CodeDescription
400Repository URL required
400Only GitHub repositories supported
401Unauthorized — valid session required
500Failed to analyze repository. The response includes a details field with the underlying error message.