API consumers have two main types of request: 'Evaluations' and 'Max Impact Fund Grants'.
Evaluations represent a Givewell assessment of the cost of a single intervention type for a single charity in one specific date range, e.g. AMF, $10 per malaria net in 2018. Grants represent the collective allocations of the Givewell Maximum Impact Fund for a specific quarter and their assessment of what the money bought, e.g. one grant for ($10000 to AMF buying 1100 bednets, and $30000 to SCI for 200 deworming treatments).
To get evaluations, send a GET request to impact.gieffektivt.no/api/evaluations, including any of the optional query strings to filter within time periods or by charities: start_year=<integer>, start_month=<integer>, end_year=<integer> end_month=<integer>, donation_year=<integer>, donation_month==<integer>, donation_day=<integer>, conversion_year=<integer>, conversion_month=<integer>, conversion_day=<integer>, charity_abbreviation=<string>, language=<i18n country code, defaulting to 'en'>, currency=<ISO 4217 code, defaulting to USD and otherwise converted from USD using previous-day conversion rate>.
Multiple charities can be requested, and all evaluations within the time specified for those charities will be returned. Absent queries default to the maximally inclusive value. Charity abbreviations are not case sensitive.
The JSON response object will contain either (a list of `errors`) or (a list of `evaluations` and optionally a list of `warnings`). Currently the only warning is that the `evaluations` list is empty, given the filter parameters entered.
To get Max Impact Fund grants, send a GET request to impact.gieffektivt.no/api/max_impact_fund_grants, including any of the optional query strings to filter within time periods: start_year=<integer>, start_month=<integer>, end_year=<integer> end_month=<integer>, donation_year=<integer>, donation_month==<integer>, donation_day=<integer>, conversion_year=<integer>, conversion_month=<integer>, conversion_day=<integer>, language=<i18n country code, defaulting to 'en'>, currency=<ISO 4217 code, defaulting to USD and otherwise converted from USD using previous-day conversion rate>.
The JSON response object will contain either (a list of `errors`) or (a list of `max_impact_fund_grants` and optionally a list of `warnings`). Currently the only warning is that the `max_impact_fund_grants` list is empty, given the filter parameters entered.
To get All Grants Fund grants, send a get request to impact.gieffektivt.no/api/max_impact_fund_grants. The parameters are otherwise the same as for Max Impact Fund Grants.
We currently have two grant types which duplicate each others' code. To add more we might want to refactor associated code into base classes, but to naively repeat the process of adding one, see the changes in commit 71ff5b0, 'Add add All Grants Fund grants, and new evaluation and allotment fields'
For any query, if language is given but no currency, currency will default to the natural currency for that language (eg NOK for Norway, USD for English). Language options are currently only English and Norwegian. Currency can be converted to most major denominations. Adding a language has to be done codeside with the following steps:
- In impact_api/settings.py, add the language details to the `LANGUAGES` tuple
- In impact_api/api/serializers.py, add the language and its default currency to the `DEFAULT_LANGUAGE_CURRENCY_MAPPING` dictionary
- From the command line, run `python manage.py makemigrations`
- Check the migration has been created with your desired language. Then from the command line, run `python manage.py migrate`
- Once the database in question is up to date, make sure to populate all the existing 'Intervention' fields to ensure that someone requesting the new language gets text
To view supported currencies, open the relevant Django shell (`python manage.py shell`), then
- `from currency_converter import CurrencyConverter`
- `c = CurrencyConverter()`
- `c.currencies`
The current list is 'AUD', 'BGN', 'BRL', 'CAD', 'CHF', 'CNY', 'CYP', 'CZK', 'DKK', 'EEK', 'EUR', 'GBP', 'HKD', 'HRK', 'HUF', 'IDR', 'ILS', 'INR', 'ISK', 'JPY', 'KRW', 'LTL', 'LVL', 'MTL', 'MXN', 'MYR', 'NOK', 'NZD', 'PHP', 'PLN', 'ROL', 'RON', 'RUB', 'SEK', 'SGD', 'SIT', 'SKK', 'THB', 'TRL', 'TRY', 'USD', 'ZAR'.
To access to the admin section, first create an admin user: from the relevant command line, run `python manage.py createsuperuser` and follow the prompts. Then you can access the admin section by visiting impact.gieffektivt.no/admin, and log in with the details you provided. From there you can create, edit and delete evaluations and grants (and associated models), as well as add other admin users.