factbookclient

README

go-factbook-client

A small Go client for the CIA World Factbook GitHub mirror — the Factbook itself is US-government public domain; this package walks and downloads its GitHub-hosted JSON mirror.

Install

go get github.com/olehmushka/go-factbook-client

Usage

c := factbookclient.New(nil)

// One GitHub git-tree API call enumerates every per-country file.
files, treeSHA, err := c.ListCountryFiles(ctx, "", "") // "" uses DefaultRepo/DefaultRef

// Download everything into a directory:
treeSHA, paths, err := c.FetchAll(ctx, "", "", "/tmp/factbook")

// ...or just the files you want:
sum, err := c.DownloadCountryFile(ctx, "", "", files[0], "/tmp/ug.json")

Scope

This client enumerates and downloads the mirror's raw per-country JSON files. It does not parse the Factbook's own document structure (e.g. extracting "Ethnic groups" or any other field) — that is application-specific interpretation of the data, left to the caller.

Notes

Built on go-govapi-core for the JSON-fetch helper and User-Agent conventions. The git-tree walk and per-file download mirror an already-shipped, already-verified integration against this same mirror in go-oikumenea's internal/hermenea/fetcher/factbook.go (its D-PhysicalIdentity / M43 ethnicity-pipeline connector) — this package is that integration's fetch layer, extracted and generalized.

License

Apache 2.0 — see LICENSE.

Documentation

Overview

Package factbookclient is a small client for the CIA World Factbook GitHub mirror (https://github.com/factbook/factbook.json) — the Factbook itself is US-government public domain; this package just walks and downloads its GitHub-hosted JSON mirror.

It enumerates every per-country `<region>/<cc>.json` file with ONE git-tree API call, then downloads whichever files the caller wants. It does not parse the Factbook's own document structure (e.g. extracting "Ethnic groups") — that is application-specific interpretation of the data, not something a generic client to this mirror should decide for its caller.

The git-tree walk and per-file download mirror an already-shipped, already-verified integration against this same mirror: https://github.com/olehmushka/go-oikumenea/blob/main/internal/hermenea/fetcher/factbook.go (go-oikumenea's D-PhysicalIdentity / M43 ethnicity-pipeline connector) — this package is that integration's fetch layer, extracted and generalized.

Index

• Constants
• type Client
  • func New(httpClient *http.Client, opts ...Option) *Client
  • func (c *Client) DownloadCountryFile(ctx context.Context, repo, ref string, file CountryFile, dest string) (string, error)
  • func (c *Client) FetchAll(ctx context.Context, repo, ref, dir string) (string, map[string]string, error)
  • func (c *Client) ListCountryFiles(ctx context.Context, repo, ref string) ([]CountryFile, string, error)
• type CountryFile
• type Option
  • func WithUserAgent(userAgent string) Option

Constants

const DefaultRef = "master"

DefaultRef is the mirror's default branch.

const DefaultRepo = "factbook/factbook.json"

DefaultRepo is the Factbook's GitHub mirror.

const DefaultUserAgent = "go-factbook-client/0.1 (+https://github.com/olehmushka/go-factbook-client)"

DefaultUserAgent identifies this client when UserAgentEnv is unset.

const UserAgentEnv = "FACTBOOK_CLIENT_USER_AGENT"

UserAgentEnv lets an operator override the outbound User-Agent with their own contact.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a Factbook GitHub-mirror client. The zero value is not usable — construct one with New.

func New

func New(httpClient *http.Client, opts ...Option) *Client

New constructs a Factbook client. httpClient nil defaults to an unbounded client (govapicore.NewHTTPClient(0)) — FetchAll downloads ~260 files in one call, better bounded by the caller's context than a fixed per-request client timeout, mirroring go-oikumenea's shipped Factbook fetcher.

func (*Client) DownloadCountryFile

func (c *Client) DownloadCountryFile(ctx context.Context, repo, ref string, file CountryFile, dest string) (string, error)

DownloadCountryFile streams one country file's raw JSON to dest and returns its sha256 checksum (hex-encoded). dest's parent directory must already exist.

func (*Client) FetchAll

func (c *Client) FetchAll(ctx context.Context, repo, ref, dir string) (string, map[string]string, error)

FetchAll lists the mirror's country files and downloads every one into dir (flattened as region__cc.json, so the destination directory stays flat regardless of the mirror's <region>/<cc>.json layout). Returns the tree SHA and a map of mirror path -> local destination path.

func (*Client) ListCountryFiles

func (c *Client) ListCountryFiles(ctx context.Context, repo, ref string) ([]CountryFile, string, error)

ListCountryFiles enumerates the mirror's per-country files with one GitHub git-tree API call. repo/ref empty use DefaultRepo/DefaultRef. treeSHA is the tree's own commit SHA — an unchanged SHA means an unchanged upstream tree, useful for a caller's own change detection. Returns an error if GitHub reports the tree as truncated (the recursive listing was too large to return in one call) rather than silently returning a partial set.

type CountryFile

type CountryFile struct {
	Path string
}

CountryFile is one per-country blob in the mirror, e.g. Path "africa/ug.json".

type Option

type Option func(*Client)

Option configures a Client constructed via New.

func WithUserAgent

func WithUserAgent(userAgent string) Option

WithUserAgent overrides the default/env-resolved User-Agent.