# factbook.json: the World Factbook country profiles as a Git repository > factbook.json mirrors the CIA World Factbook country profiles as JSON files laid out by continent, uses the original GEC codes rather than ISO codes, and works as a REST API over raw GitHub URLs with no key. Its README states the source Factbook was wound up in February 2026, and a sibling cache repository keeps the last scraped copy. **factbook/factbook.json** — World Factbook Country Profiles in JSON - Free Open Public Domain Data - No API Key Required ;-) - Repository: https://github.com/factbook/factbook.json - Stars: 1,133 · Forks: 151 - Language: Unknown - License: CC0-1.0 - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/factbook-factbook-json ## The upstream Factbook was wound up, and this repository is the copy The most important thing in this repository is a news item at the top of the README, and it changes how the whole project should be read. The README states that in February 2026 the CIA wiped out the World Factbook, linking to a CIA story titled Spotlighting The World Factbook as We Bid a Fond Farewell. The line of the entry is that, on the order of the new US administration, the Factbook was ended. So this is no longer a mirror of a live source. It is, or was, a structured copy of a dataset that no longer has a publisher, and the repository's own framing shifts accordingly. The README points readers to a tip box suggesting they ask their preferred assistant for alternate ongoing or new Factbook archive mirrors, copies, alternative world almanacs, or country profiles. That tip is a signal about the project's future direction. The core value of factbook.json was always the conversion work, scraping the HTML country profiles into JSON, and that conversion is worth more now that the source is gone, because the JSON is the remaining machine-readable form of the data. The repository is not archived, the last push was on 2026-09-11, and the licence situation is clean, with the repository metadata listing CC0-1.0 and the package manifest saying Public Domain. ## A REST API made of raw file URLs The FAQ section answers a question that reveals the project's design intent. Asked whether there is an open source REST HTTP API for the World Factbook, the answer is that factbook.json is one. The mechanism is GitHub's raw file serving. To get the country profile for Germany, whose code is gm, you request the raw URL for the file at europe/gm.json on the master branch. The full example given is https://github.com/factbook/factbook.json/raw/master/europe/gm.json, and the note is that no API key is required. Fetching a profile is an ordinary HTTP request: ```bash curl https://github.com/factbook/factbook.json/raw/master/europe/gm.json ``` That is a clever reuse of infrastructure. There is no server to run, no rate limit to negotiate, no token to rotate, and no availability guarantee beyond GitHub's own. A frontend can fetch a country profile directly with a plain fetch call, and the same URL works in a browser, in a script, or in a notebook. The cost is that the API surface is a filesystem, so the things an API would give you are either absent or awkward. There is no schema endpoint, so a client cannot discover the shape of the data before requesting it. There is no query language, so a request for every country with a population over ten million means fetching every file and filtering locally. And there is no versioning, so a change to the upstream scrape changes the data under the same URL without notice. For a dataset of 260 country profiles, that trade is often the right one. For a dataset you intend to query at scale, it is a decision to make consciously. ## GEC codes, not ISO codes, and why that is deliberate Every profile in this repository is named with the original two-letter GEC code, formerly FIPS, rather than the ISO 3166 code most developers expect. The README is emphatic about it: au.json is Austria and not at.json, gm.json is Germany and not de.json, and so on. The FAQ explains the reasoning in detail, and the reason is that the mapping is not one to one. The Factbook has more entities than ISO, and sometimes with a different definition, so it is not an easy 1:1 mapping, and the README links to the Factbook's own cross-reference list of country data codes as the authority. A worked example makes the awkwardness concrete. Someone noticed that Zambian data appeared under ZA in the African region, and pointed out that it should be South African data. The reply is that the Factbook stores it under SF. Weird, but acceptable. The point is that SF is the code the Factbook uses for Zambia, and a consumer who has silently mapped GEC to ISO would file that data against the wrong country. This is the single most likely way to get burned when using this dataset. Any join against a table of ISO codes needs the explicit cross-reference rather than a string replacement, and a naive approach produces plausible-looking but wrong results. ## How the weekly update job works and what it depends on The answer to whether the datasets can be updated describes an automation that has been running since August 2021. The datasets are auto-updated by fetching the original online CIA World Factbook country profile datasets, and the raw scrape is cached in a separate repository, cache.factbook.json, with the fetch happening weekly, every Thursday. The README points at the GitHub Actions log for details. The architecture is a sensible two-repository split. The cache repository holds the raw scraped material, and factbook.json holds the converted, region-organised JSON. A workflow fetches, converts, and commits, which means the conversion is reproducible from a known raw snapshot, and you can diff the cache repository to see exactly what changed upstream between two runs. The word cache is doing quiet work in that sentence. It implies a copy of something that no longer exists upstream, and the README's February 2026 news entry says the source was ended. So the weekly job's status after that date is the open question for anyone relying on the data staying current, and the README offers no statement about it. The repository listing shows the same structure on disk. There are continent directories, africa/, antarctica/, australia-oceania/, central-america-n-caribbean/, central-asia/, east-n-southeast-asia/, europe/, middle-east/, north-america/, oceans/, south-america/ and south-asia/, plus a meta/ directory and a world/ directory for the global entry. That regional split is what makes a raw URL for a single country profile work, since the path has to resolve to exactly one file. ## The JSON shape is section, then topic, then text The example given for Austria shows the document structure, and it is worth understanding because it is what a consumer has to traverse. The top level is a set of named sections such as Introduction and Geography. Within a section there are topics, for example Location, Geographic coordinates, Map references and Area, and within a topic there is either a text value or a nested object of subtopics. Area is an object with total, land and water, each holding a text field. Land boundaries is an object with total and border countries. Elevation is an object with lowest point and highest point. The uniform convention is that the leaf is a text property, and the values are human-readable strings rather than parsed numbers. Area total is 83,871 sq km as a string, not 83871 as a number. Elevation highest point is Grossglockner 3,798 m as a string. The geographic coordinates are 47 20 N, 13 20 E as a string. That choice is faithful to the source, which is prose, and it is convenient for display. It is inconvenient for analysis, because every figure requires parsing, and the units are embedded in the text rather than declared. A consumer that wants to compare areas across countries is doing string work, and the ones that write the comparison have to deal with thousands separators, differing unit spellings, and values that are sometimes approximations. For a display-oriented client, for example a country profile page, the structure works well. For a data pipeline, the transformation to typed numeric fields is a job you have to do yourself. ## 260 entries, and the six that are not there The summary table is stated in the README with the strikethrough edits left visible, which tells the story of the count changing. The Factbook includes 266 entries per its own front page, but this repository has 260. The breakdown is 195 sovereign countries, 2 others, 52 dependencies where the number used to be 58, 5 miscellaneous, 5 oceans and 1 world. The FAQ explains the difference of six entities, and the answer is a consolidation rather than a deletion. Since March 2006 the United States Pacific Island Wildlife Refuges profile, with code um, consolidates seven separate profiles into one. Those seven are Baker Island with code fq, Howland Island with hq, Jarvis Island with dq, Johnston Atoll with jq, Kingman Reef with kq, Midway Islands with mq and Palmyra Atoll with lq. The entity count is kept as it was before, so the profile consolidates without reducing the total. The other change is a deletion. The Western Sahara profile, code wi, was dropped by the Factbook in December 2020, and the README gives the reason: in a deal with Morocco, the United States recognised Morocco's claim over the Western Sahara and in return Morocco started official diplomatic relations with Israel. The entry is preserved in the README as a code, name and category line, with the category given as Miscellaneous and the region as Africa. Both cases are a reminder about what a mirror contains. A profile that disappears upstream disappears here too, and the reason is usually political rather than editorial, so the count of 260 is a fact about the source as much as about the mirror. ## The documentation files and how to query the data Alongside the country profiles, the repository carries four documents that tell you what the project is and how to use it. ALMANAC.md, NOTES.md, SUMMARY.md and MONGO.md sit at the top level next to the README and the LICENSE.md. MONGO.md is the one with practical instructions, holding query examples and import instructions for MongoDB taken from another talk. The Background section of the README points to a further resource, the author's talk slides and notes titled Turn the World Factbook into Open (Structured) Data, which describes how the project started. The MongoDB document is the one to read first if you are building something. A country profile is a nested document with a stable top-level shape, and a document store handles that without flattening, which is the practical argument for using this data with MongoDB rather than a relational table. It also gives you a ready-made import path rather than making you write a loader for a directory tree of JSON files. The repository manifest is minimal, with the package name factbook.json, version 1.0.0, a description, the repository URL, keywords, the author Gerald Bauer, and the licence Public Domain. There are no dependencies, no build script and no install step, because there is nothing to build. The data is the repository. The author is also behind the factbook/cache.factbook.json repository and the MONGO.md companion notes, and the README closes with an invitation to explore the world with JSON datasets, which is a reasonable attitude for a repository that has just become the most accessible copy of a dataset that no longer has a publisher. ## Conclusion factbook.json is a good fit for a project that needs country profile data as structured JSON without registering for an API key or writing a scraper, because the repository layout, the weekly update job and the public domain status remove all three of those obstacles; it is the wrong choice if you need the data to stay current, because the README states the upstream Factbook was wound up in February 2026, so before you build on it you should check the sibling cache.factbook.json repository and confirm how far the automated updates actually run. ## FAQ ### Is there an API for the World Factbook data in factbook.json? The repository states that it is one, served through GitHub raw file URLs with no API key required. For example, the profile for Germany, whose code is gm, is at https://github.com/factbook/factbook.json/raw/master/europe/gm.json. ### Why does factbook.json use GEC codes instead of ISO country codes? The Factbook has more entities than ISO and sometimes with a different definition, so it is not an easy one to one mapping, and the README points at the Factbook's cross-reference list of country data codes. Austria is au.json and Germany is gm.json rather than at and de. ### How often is the factbook.json data updated? The README states that since August 2021 the datasets have been auto-updated by fetching the original online CIA World Factbook country profile datasets, which are cached in the separate cache.factbook.json repository, weekly on Thursdays, by a GitHub Action. ### What happened to the CIA World Factbook? The README states that in February 2026 the CIA wound up the World Factbook entirely, linking to the CIA story Spotlighting The World Factbook as We Bid a Fond Farewell, and suggests looking for alternative archive mirrors or other country profile sources. ### What licence is the factbook.json data under? The licence field in the repository metadata gives CC0-1.0 and the package manifest says Public Domain, with the text in LICENSE.md. ## Sources - [factbook/factbook.json on GitHub](https://github.com/factbook/factbook.json) - [Issues](https://github.com/factbook/factbook.json/issues) - [License: CC0-1.0](https://github.com/factbook/factbook.json/blob/master/LICENSE) - [README](https://github.com/factbook/factbook.json/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/factbook-factbook-json