This is a Python library to help one use APIv2 to fetch the data from the database JoshuaProject.net 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.

Install

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 (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 = cc.data[cc.data.FIPS != cc.data.ISO]
len(diff)/len(cc)

0.6024096385542169
diff.head()
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

Solution: The library provides a CountryCodes() class to workaround this discrepancy.

Missing FIPS codes

Missing FIPS values:

cc.data[cc.data.FIPS.isna()]
cname FIPS ISO
1 Aland Islands NaN AX
27 Bonaire, Sint Eustatius and Saba NaN BQ
236 United States Minor Outlying Islands NaN UM 
cc.like('United')

[{'cname': 'Tanzania, United Republic of', 'FIPS': 'TZ', 'ISO': 'TZ'},
 {'cname': 'United Arab Emirates', 'FIPS': 'AE', 'ISO': 'AE'},
 {'cname': 'United Kingdom', 'FIPS': 'UK', 'ISO': 'GB'},
 {'cname': 'United States', 'FIPS': 'US', 'ISO': 'US'},
 {'cname': 'United States Minor Outlying Islands', 'FIPS': nan, 'ISO': 'UM'}]

For more details, see the Country Codes page.

URL Constructing Functions

There are a few functions to easily construct URLs to query then for the info required.

Get all people groups in a specific country

Build an URL to query all people groups in India:

url_pgs_cntry('IN',api_key=api_key)

'https://joshuaproject.net/api/v2/people_groups?ROG3=IN&api_key=your_api_key'

For more details, see the URL Functions page.

Development

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

Testing

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.

Contributing

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.