Skip to main content

Python library for

Project description

Joshua Project Python Library

This is a Python library to help one use APIv2 to fetch the data from the database web site.

This library uses Joshua Project's APIv2. You'll need an api_key to use API and the library. For details, see Documentation.


pip install joshuaproject

How to use

Get your API key and set it in a variable or pass to functions.

Country Codes

Joshua Project uses FIPS codes (US Federal Information Processing Standard) for countries.

[FIPS 10-4](https: // (April 1995) -- Countries, Dependencies, Areas of Special Sovereignty, and TheirPrincipal Administrative Divisions.

However, FIPS 10-4 was withdrawn by NIST on September 2, 2008 in favor of the international ISO 3166 standard.

In the meantime, as of Jan 2020 Joshua Project has no plans to switch onto ISO codes, I was notified. sigh

Sadly, FIPS in 60% cases differs from the ISO.

cc = CountryCodes()
diff =[ !=]
<style scoped> .dataframe tbody tr th:only-of-type { vertical-align: middle; }
.dataframe tbody tr th {
    vertical-align: top;

.dataframe thead th {
    text-align: right;
cname FIPS ISO
1 Aland Islands NaN AX
3 Algeria AG DZ
4 American Samoa AQ AS
5 Andorra AN AD
7 Anguilla AV AI


This library provides a CountryCodes() class to workaround this discrepancy.

Missing FIPS codes

Missing FIPS values:[]
<style scoped> .dataframe tbody tr th:only-of-type { vertical-align: middle; }
.dataframe tbody tr th {
    vertical-align: top;

.dataframe thead th {
    text-align: right;
cname FIPS ISO
1 Aland Islands NaN AX
27 Bonaire, Sint Eustatius and Saba NaN BQ
236 United States Minor Outlying Islands NaN UM'French')
[{'cname': 'French Guiana', 'FIPS': 'FG', 'ISO': 'GF'},
 {'cname': 'French Polynesia', 'FIPS': 'FP', 'ISO': 'PF'},
 {'cname': 'French Southern Territories', 'FIPS': 'FS', 'ISO': 'TF'}]

URL Constricting finctions

2. Get all people groups in a specific country.

Build an URL to query all people groups in India:



All phases of development (coding, testing, documentation -- autogenerated) are being done completely inside Jupyter Notebooks, thanks to the excellent tool nbdev by team.


Tests are incorporated into the Jupyter Notebooks and are also a neat way to learn the function's expected behavior, since in case of incorrect behavior test_* functions will return an AssertionError.

Tests can also be launched from the console with nbdev_test_nbs.


Ideas, issues and pull-requests are welcome! Please submit via GitHub.

Please share, like and upvote, too.


Copyright 2020 onwards, Konstantin Dorichev. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project's files except in compliance with the License. A copy of the License is provided in the LICENSE file in this repository.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

joshuaproject-0.0.5.tar.gz (11.1 kB view hashes)

Uploaded source

Built Distribution

joshuaproject-0.0.5-py3-none-any.whl (10.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page