Codelists¶
Introduction¶
The 360Giving Data Standard includes over 100 different data fields with specific names and rules about the format of the information that can be shared in each field.
There are some fields where the values that can be provided are also strictly regulated, requiring the use of a code from a specific codelist.
For example, the 360Giving Data Standard includes a field for Currency which requires publishers to use the International Organization for Standardization’s (ISO) standardised set of codes, called ISO 4217. This means that instead of the data in this field describing the currency in various ways – such as “£” or “pounds” or “Pound Sterling” – the currency is “GBP”. 360Giving also makes use of standardised two-letter country codes taken from ISO 3166-1 alpha-2. This makes 360Giving data more interoperable between 360Giving publishers and also enables it to be used alongside other non-360Giving datasets.
Although many fields and types of information are not suitable for standardisation in the form of a codelist, common codes should be used whenever possible. In autumn 2022, upgrades to the 360Giving introduced four new codelists into the Standard for the first time, which have been developed through consultation with data publishers and users.
This guidance explains the codelists used in 360Giving Data Standard and how to publish and use them.
What are codelists?¶
Codelists are a list of values. Each value has three elements:
- a short name, which is designed for humans to read and understand
- a description, which explains to humans the meaning behind the code so that we can interpret it
- and the code, which is included in the data
If you have ever used a web form and selected a value from a drop-down list, this is very similar to how codelists function.
The reason for using codes instead of names is because it avoids issues caused by typos, spaces or different cases. It also means the accompanying name and description can be amended or translated without the codes needing to be changed.
Open and closed codelists¶
Codelists can be closed or open.
Closed codelists¶
These are intended to be comprehensive. For example, the currency codelist covers all currencies in the world.
When a codelist is closed it means that publishers must only use the codes in the codelists, and cannot add new codes if there is no appropriate code for them to use.
Open codelists¶
These are intended to be representative, but not comprehensive.
When a codelist is open it means that publishers may use a new code outside those in the codelist, if there is no appropriate code for them to use.
The codelists used in the Standard¶
There are seven codelists used in 360Giving Data Standard.
Two codelists, Currency and Country code are managed by ISO and the five remaining codelists are managed directly by 360Giving.
Managed externally
Managed by 360Giving
All the codes used in the Standard are alphanumeric and case sensitive.
The codelists in the 360Giving Data Standard are closed in type. This means that you may only use the codes listed in the codelists.
For the codelists managed directly by 360Giving, if there is no appropriate code to use, it is possible to propose new codes be added to the list. Further information about how to propose new codes is set out in Versioning and Upgrade Process.
Currency¶
A codelist with values to specify the currency used in amounts. For example GBP is the code for Pounds Sterling.
The codes from this codelist can be published in the Currency field, and also appear in the Transactions object.
To view the full list of codes visit ISO 4217.
Country code¶
A codelist with values to specify the 2-character ISO Country Code of a location. For example GB is the code for the United Kingdom of Great Britain and Northern Ireland.
The codes from this codelist can be published in three fields:
- Recipient Org:Location:Country Code
- Funding Org:Location:Country Code
- Beneficiary Location:Country Code
The Geocode fields are part of objects which are an array. This means that multiple iterations of the field can be included when a publisher has more than one location to share per grant.
To view the full list of codes visit ISO-3166-1-alpha-2.
GeoCode Type¶
A codelist with values to specify which type of UK geographical code has been provided in the associated Geocode field.
The codes from this codelist can be published in three fields:
- Recipient Org:Location:Geographic Code Type
- Funding Org:Location:Geographic Code Type
- Beneficiary Location:Geographic Code Type
The Geocode Type fields are part of objects which are an array. This means that multiple iterations of the field can be included when a publisher has more than one location to share per grant.
Regrant Type¶
A codelist with values to specify that a grant is intended for redistribution, broken down into seven types of regrant.
The codes from this codelist can be published in the field For Regrant Type. The For Regrant Type field can only be included once with a single code per grant.
For further explanation of how to use the Regrant Type codelist, including examples, read the 360Giving guide to regranting.
| Code | Title | Description |
|---|---|---|
| FRG010 | Common Regrant | A grant awarded to a single grantmaking organisation for onward distribution as grants to end recipients. |
| FRG020 | Transfer to intermediary | A grant awarded to an intermediary, such as a network or federated charity, for distribution as payment to organisation(s) for redistribution as grants to end recipients. |
| FRG030 | Match funding | A grant awarded to grantmaking organisations for match funding and onwards distribution as grants to end recipients. |
| FRG040 | Funder collaboration | Grants awarded by multiple funders to a single grantmaking organisation to create a fund for redistribution as grants to end recipients. |
| FRG050 | Fiscal sponsor | Grant awarded to an organisation acting as an agent for the funder, to make grant payment on its behalf to the defined recipient(s). |
| FRG060 | Endowment | A single grant awarded or transfer of capital to either establish or substantially fund a grantmaking organisation or Fund. |
| FRG070 | Multipurpose | Grant to recipient for activities that include making onward grants, as well as funding other activities not related to the distribution of grants. |
Location Scope¶
A codelist with values to specify a grant‘s geographical scope, broken down into seven levels.
The codes from this codelist can be published in the field Location Scope. The Location Scope field can only be included once with a single code per grant.
For further explanation of the location scope codelist, including examples, read the 360Giving guide to location data.
| Code | Title | Description |
|---|---|---|
| GLS010 | Global | The location scope is global. |
| GLS020 | Supranational | The location scope is a supranational region or continent. |
| GLS030 | National | The activity scope covers a country, as defined by ISO 3166. |
| GLS040 | Subnational region | The activity scope covers a first-level subnational administrative area. |
| GLS050 | Local authority | The activity scope covers a second-level subnational administrative area. |
| GLS060 | Local area | Location scope covers a small area. |
| GLS099 | Undefined | The location scope is undefined. |
Grant to Individuals Purpose¶
A codelist with values to specify the purpose of the grant, in terms of what the funding will be used for. This codelist is intended for use in grants to individual recipients only.
The codes from this codelist can be published in the field To Individuals Details:Grant Purpose.
The To Individuals Details:Grant Purpose field is an array. This means that when a grant has more than one purpose it is possible to include multiple codes in this field, separated by a semi-colon.
Please note: This is the only codelist field that is an array. All other fields in the 360Giving Data Standard which use codelists only allow a single code per field.
| Code | Title | Description |
|---|---|---|
| GTIP010 | Unrestricted | Unspecified, unrestricted or general support |
| GTIP020 | Furniture and appliances | Furniture, garden and outdoor play equipment, white goods, home appliances |
| GTIP030 | Equipment and home adaptations | Safety equipment, specialist equipment, baby equipment, toys, home adaptations, mobility aids |
| GTIP040 | Devices and digital access | Computers, phones, mobile devices, technology / digital access |
| GTIP050 | Utilities | Energy, water, telephone, TV/entertainment licences, broadband costs - including set-up and meter installation |
| GTIP060 | Other housing related costs | Deposits, rent, mortgage contributions, council tax, arrears, decoration, removal costs, deep cleans |
| GTIP070 | Food and essential items | Food, toiletries, nappies, cleaning products, all essential living costs |
| GTIP080 | Clothing | School uniforms, children’s clothing, workwear, essential clothing |
| GTIP090 | Debt | Credit card debits, non housing-related debts, bankruptcy |
| GTIP100 | Travel and transport | Travel or transport costs including public transport, petrol and repairs |
| GTIP110 | Holiday and activity costs | Family activities, school trips, holidays, sport activities, social activities, breaks for carers |
| GTIP120 | Health, care and wellbeing services | Medical, childcare costs, therapy, dental work, physiotherapy, addiction recovery support, domiciliary/residential care costs, temporary accommodation for patients and carers |
| GTIP130 | Education and training | Tuition, boarding school fees, university fees, books/resources and essential course costs, scholarships, fellowships, PhDs, support for exceptional talent, personal/professional development, sports coaching/development, capacity building |
| GTIP140 | Employment and work | Employment support, business start-up costs, apprenticeships, social enterprise, work ready support |
| GTIP150 | Creative activities | Freelance art and cultural projects and activities, musical instruments |
| GTIP160 | Community projects | Social action, community projects, campaigns and activism |
| GTIP170 | Exceptional costs | Funeral costs, crisis funding, legal fees, benefits applications and time pending benefits receipt |
Grant to Individuals Reason¶
A codelist with values to specify the reason that the grant was awarded to the recipient. This codelist is intended for use in grants to individual recipients only.
The codes from this codelist can be published in either of two fields, To Individuals Details:Primary Grant Reason and To Individuals Details:Secondary Grant Reason. Each field can only be included once with a single code per grant.
| Code | Title | Description |
|---|---|---|
| GTIR010 | Financial Hardship | Low income, debt, poverty |
| GTIR020 | Disability | Physical, mental or learning disability, difficulty or difference |
| GTIR030 | Health/Condition | Limiting health condition(s) or illness(es), substance misuse, of individual or family members |
| GTIR040 | Mental Health | Mental health condition(s) or illness(es), wellbeing, of individual or family members |
| GTIR050 | Family breakup | Breakdown of family cohesion/stability, estrangement, single parent |
| GTIR060 | Violence or abuse | Domestic violence or abuse, fleeing other violence, neglect |
| GTIR070 | Livelihood | Loss of job or source of income, underemployment, zero hours contracts, reduced hours or income, time out of work for caregiving, sustaining business/livelihood |
| GTIR080 | Homelessness | Homeless or poorly or vulnerably housed |
| GTIR090 | Marginalised | No recourse to public funds, care leavers, people in or leaving the criminal justice system, other marginalised or vulnerable people or people with barriers to access |
| GTIR100 | Emergency/crisis event | Need driven by an incident such as death of a family member or disaster such as housing flood, fire etc, victim of crime |
| GTIR110 | Development opportunity | Skills development, scholarships, artist development, exceptional talent, sporting talent |
| GTIR120 | Social action | Supporting a community or cause not solely driven by the needs of the individual receiving the grant, campaigns, community development |
How to use codelists in 360Giving data¶
Only codes from the codelists may be used. Any other code included in the data will result in invalid data. Please be aware that the codes are also case sensitive. Reproduce uppercase and lowercase letters in the codes correctly or the code will not be recognised and your data will be invalid.
Only one code is allowed per field, and it is not possible to include comma separated lists of codes in a single field. If the field is an array (see Reference) then you may use more than one code from the codelist in a spreadsheet by adding columns utilising the Numbering technique, which is used elsewhere for describing multiple occurrences of e.g. Locations.
Codes may not be applicable to all grants. When a grant has no relevant code, the field must be left blank. Do not use filler values such as N/A — a codelist field must only be populated with valid codes or left blank.
Adding extra information¶
The code names can be included in Title or Description text fields to help users of the data.
Including the code names and descriptions in additional non-Standard fields may also be helpful when preparing the data, and for data users.
However, be aware that only the codes themselves are validated by 360Giving tools, and the additional data fields will not be included in data downloads provided by 360Giving tools.
Examples¶
Regrant Type
| Identifier | Description | Amount Awarded | For Regrant Type |
|---|---|---|---|
| 360G-ExampleFdn-001 | Contribution to pooled fund for charities supporting local residents | 50000 | FRG040 |
| 360G-ExampleFdn-002 | Contribution to salary of benefits adviser | 10000 | |
| 360G-ExampleFdn-003 | To be awarded as grants to small arts organisations | 25000 | FRG010 |
| 360G-ExampleFdn-004 | To fund outdoor play equipment for nursery | 5000 |
Grant To Individuals Codelists
| Identifier | To Individuals Details:Primary Grant Reason | To Individuals Details:Secondary Grant Reason | To Individuals Details:Grant Purpose |
|---|---|---|---|
| 360G-ExampleFdn-001 | GTIR010 | GTIR030 | GTIP070;GTIP080 |
| 360G-ExampleFdn-002 | GTIR010 | GTIR100 | GTIP020;GTIP030;GTIP040 |
Getting further help
This guidance aims to support funders through the 360Giving publishing process. If you can't find the information you need or you have further questions email 360Giving Helpdesk. You can help us improve this guidance by filling out our feedback form.