HXL hashtag dictionary (version 1.0 alpha)

Note: this is an obsolete version of the HXL standard, preserved for historical reference. If you are implementing or supporting HXL, please refer to the current version of the standard.

Release 1.0alpha (2014-08-28; updated 2014-10-07)

1. Introduction

This page suggests some basic hashtags for the Humanitarian Exchange Language (HXL). You add these tags in a row after the last header row in a spreadsheet, leaving a cell blank if you do not want to tag the column, then include the spreadsheet data afterwards. For more information about using these tags, please see HXL tagging conventions.

See also the proposed new HXL hashtags that may appear in this standard in the future.

1.1. Tag format

The HXL tags recommended here are all lower case. The core tag is always alphanumeric (e.g. “#sector”). For tags that point to specific data types, there is also a suffix to indicate that datatype (e.g. “#adm3_id”):

(none) Plain, human-readable text (e.g. a placename).
_date A date or time period (e.g. 2012).
_deg Degrees of latitude or longitude.
_id A code or unique identifier (e.g. a P-code from the Common Operational Datasets).
_lnk A URL (web link).
_num A numeric value.

2. Baseline tags

These tags are recommendations from the HXL working group. You are free to create your own hashtags for any types of information not covered here, but using the baseline tags (when possible) can help make it easier for others to use your data.

There are several categories of suggested hashtags:

2.1. Tags for reporting metadata

HXL tag Title Data type Description Example
#report_date Date reported Date The date that this data record was released. 2014-06-23
#from_date Start date applicable Date The date when the data in this report was first applicable. 2014-05-01
#to_date End date applicable Date The date when the data in this report was last applicable. 2014-05-31
#period_date Time period applicable Date The time period when the data in this report was applicable. 2010
#source Source description Text A free-text description of the source organisation for this data record. OXFAM GB
#source_id Source id Code A unique identifier for the source organisation for this data record. 5120
#method Methodology description Text A free-text description of the methodology used to collect the data in this record. Census
#method_id Methodology code Code A unique code for the methodology used to collect the data in this record. 003
#method_lnk Methodology link URL A link to an online description of the methodology. http://example.org/project3/methodology.html
#datatype Data type description Text A free-text description of the type of data being collected. Who-What-Where (3W)
#datatype_id Data type code Code A unique code for the type of data being collected. CX569
#crisis Crisis description Text A free-text description of the crisis to which the data applies. Complex Emergency, Israel
#crisis_id Crisis id Code An unique identifier for the crisis to which the data applies. 2012-000194
#crisis_lnk Crisis link URL A link to an online description of the crisis.  
#data_lnk Data origin link URL A link to an online source for this specific data (API, PDF, etc.).  

2.2. Tags for location

HXL tag Title Data type Description Example
#loc Location description Text A free-text description of a specific location. Capital Health Clinic
#loc_id Location code Code A code uniquely identifying a location. Normally, a p-code from the COD registry for the country. 083700000
#loctype Location type Text Description of a location type. Camp
#loctype_id Location type code Code A code uniquely identifying a location type. 01hosp
#country Country description Text A free-text description of a country. Philippines
#country_id Country code Code A code uniquely identifying a country, normally an ISO 3166-1 alpha-3 code. PH
#region Region description Text A free-text description of a super-national region (e.g. “Sahel”). Asia-Pacific
#region_id Region code Code A code uniquely identifying a super-national region. APC
#adm Full admin description Text A free-text description of all administrative levels combined Sawa, Magsaysay, Occidental Mindoro, Mimaropa
#adm1 Admin level 1 description Text A free-text description of a level-one administrative area (ADM1). Central Province
#adm1_id Admin level 1 code Code A code uniquely identifying a level-one administrative area (ADM1). 2
#adm2 Admin level 2 description Text A free-text description of a level-two administrative area (ADM2). Nyeri Division
#adm2_id Admin level 2 code Code A code uniquely identifying a level-two administrative area (ADM2). 205
#adm3 Admin level 3 description Text A free-text description of a level-three administrative area (ADM3). Mathira District
#adm3_id Admin level 3 code Code A code uniquely identifying a level-three administrative area (ADM3). 20503
#adm4 Admin level 4 description Text A free-text description of a level-four administrative area (ADM4). Sawa baranguay
#adm4_id Admin level 4 code Code A code uniquely identifying a level-four administrative area (ADM4).  
#adm5 Admin level 5 description Text A free-text description of a level-five administrative area (ADM5).  
#adm5_id Admin level 5 code Code A code uniquely identifying a level-five administrative area (ADM5).  
#lat_deg Latitude Number The decimal latitude of the location (e.g. 40.500000 for north 40 degrees, 30 minutes, 0 seconds). 13.216667
#lon_deg Longitude Number The decimal longitude of the location (e.g. -70.250000 for west 70 degrees, 15 minutes, 0 seconds). 120.600000

2.3. Tags for demographic information

HXL tag Title Data type Description Example
#sex Sex category description Text A free-text description of a sex category. Male
#sex_id Sex category code Code A unique code for a sex category. m
#age Age category description Text A free-text description of an age category. Infants (under 3)
#age_id Age category code Code A unique code for an age category. 0-3
#agesex Age/sex category description Text A free-text description of a combined age-sex category. Girls 6-12
#agesex_id Age/sex category code Code A unique code for a combined age-sex category. g_6_12
#people_num Number of people involved Number Number of people involved (without specifying status). 900
#households_num Number of households involved Number Number of households involved (without specifying status). 350
#females_num Number of females involved Number Number of females involved (without specifying status). 1000
#males_num Number of males involved Number Number of males involved (without specifying status). 800
#origin Place of origin description Text Place of origin of a person or group. Syria
#origin_id Place of origin code Code Unique identifier for the place of origin of a person or group. SYR

2.4. Tags for impact and needs

HXL tag Title Data type Description Example
#aff_num Number of people affected Number Total number of affected people described in this data record/row. 150000
#impact1 Impact type level 1 description Text Free-text description of the impact at a general level of detail. Affected
#impact1_id Impact type level 1 code Code Code for the impact at a general level of detail. V100
#impact2 Impact type level 2 description Text Free-text description of the impact at a medium level of detail. Displaced
#impact2_id Impact type level 2 code Code Code for the impact at a medium level of detail. V110
#impact3 Impact type level 3 description Text Free-text description of the impact at a specific level of detail. IDP
#impact3_id Impact type level 3 code Code Code for the impact at a specific level of detail. V111
#shelter1 Shelter type level 1 description Text Free-text description of the group’s shelter type at a high level of detail. Camp or Camp-Like
#shelter1_id Shelter type level 1 code Code Code for the group’s shelter type at a high level of detail. A10
#shelter2 Shelter type level 2 description Text Free-text description of the group’s shelter type at a specific level of detail. Reception or Transit Site
#shelter2_id Shelter type level 2 code Code Code for the group’s shelter type at a specific level of detail. A14
#inneed_num Number of people in need Number Number of people in need of (some kind of) assistance. 1200000
#targeted_num Number of people targeted Number Number of people targetted for (some kind of) assistance. 750000
#reached_num Number of people reached Number Number of people reached with (some kind of) assistance. 237,805
#injured_num Number of people injured Number Number of people injured. 15,000
#idp_num Number of internally-displaced people Number Number of internally-displaced people (not refugees). 1,119
#refugee_num Number of refugees Number Number of refugees from a country or area. 2,050

2.5. Tags for activities and outputs

HXL tag Title Data type Description Example
#activity Project/activity description Text A free-text title/description of the project or activity. Drought-resistant seed distribution
#activity_id Project/activity id Code A unique identifier for the project or activity. PF2014-7795
#status Project/activity status description Text A free-text description of the status of the project/activity. Currently active
#status_id Project/activity status code Code A code identifying the status of the project/activity. active
#name Contact name Text The name of the contact person for the project/activity. Jeanne Gervais
#email Contact email Email The email of the contact person for the project/activity. jgervais@example.org
#phone Contact phone Phone number The phone number of the contact person for the project/activity. +1-613-555-1111
#org Organisation description Text A free-text description of an organisation involved in an activity (without specifying role). World Food Programme (WFP)
#org_id Organisation id Code A unique identifier for an organisation involved in an activity (without specifying role). 561
#prog Programmer description Text A free-text description of the organisation programming the project/activity. World Food Programme (WFP)
#prog_id Programmer id Code A unique identifier for the organisation programming the project/activity. 561
#impl Implementer description Text A free-text description of the organisation implementing the project/activity. Canadian Food Grains Bank
#impl_id Implementer id Code A unique identifier for the organisation implementing the project/activity. 5804
#funder Funder/donor description Text The name of a funder/donor for the activity. USAID
#funder_id Funder/donor id Code A unique identifier for a funder/donor for the activity. 590.us
#sector Sector/Cluster description Text A free-text description of the cluster in which a project/activity is taking place. Food Security
#sector_id Sector/cluster code Code A code identifying the cluster in which a project/activity is taking place. FS
#subsector Subsector description Text A free-text description of a subsector to which the project/activity applies. Agriculture capacity
#subsector_id Subsector code Code A code identifying a subsector to which the project/activity applies. F0104
#output Output indicator description Text A free-text description of an output indicator targetted by the project/activity. Change in production compared to previous year’s harvest by commodity
#output_id Output indicator code Code A code identifying an output indicator targetted by the project/activity. F-12
#beneficiary Beneficiary description Text A free-text description of an intended beneficiary group for the project/activity. Agricultural food producers
#beneficiary_id Beneficiary code Code A code identifying an intended beneficiary group for the project/activity. FS/11/16
#delivered_num Number of items delivered. Number The number of units of aid delivered, however those units are defined (in the output indicator above). 3,000

A. Change history

Date Author Changes
2014-10-07 David Megginson Fixed typos, and added some Kenyan p-codes as examples.
2014-08-28 David Megginson Moved from Google Sheets to hxlstandard.org. Designated as “1.0alpha”
2014-08-14 David Megginson
  • added #idp_num and #refugee_num
2014-07-29 David Megginson
  • renamed #origin_link to #data_link to avoid confusion
  • added #origin and #origin_id to support UNHCR data”
2014-07-28 David Megginson Refine demographic tags for refugee/displacement reporting:

  • added #loctype and #loctype_id
  • added #people_num, #households_num, #females_num, #males_num”
2014-07-23 David Megginson Major rewrite:

  • started referring to “”Tags”” instead of “”Codes””, to follow new hashtag-type approach
  • added “”#”” to the start of every tag by analogy with hashtags, and replace “”.”” with “”_”” to respect hashtag syntax
  • removed column with old three-character alphanumeric codes
  • removed all deprecated codes from 2014-06-27
  • removed section numbers
2014-06-27 David Megginson Major rewrite:

  • replaced three-character alphanumeric codes with human-readable codes (kept the old codes for reference in their own column)
  • deprecated all properties for code sources (it’s not a current practice in the humanitarian community to cite sources for codes)
  • deprecated codes related to administrative subdivision levels 6 and 7 and latitude/longitude accuracy in the Location section
  • added new codes for age/sex categories in the Demographics section
  • added new code for number of items delivered (output) in the Activities and outputs section”
2014-06-11 David Megginson Added 003 time period applicable (single date) to the Metadata section. Added AB0 Number of people injured to the Impact and needs section.
2014-06-09 David Megginson Added links for methodology, crisis, and data origin to the metadata section. Added number of people targeted, in need, and reached in the Impact and needs section.
2014-05-30 David Megginson Add codes for activity status (3W).
2014-05-15 David Megginson Add codes to identify a crisis.
2014-05-05 David Megginson Renumbered codes to leave space for future additions.
2014-04-29 David Megginson Added codes specific to impact and needs (Humanitarian Profile).
2014-04-28 David Megginson Added descriptions and examples. Added codes specific to 3W data. Start using letters as well as numbers in the codes.
2014-04-17 David Megginson Initial draft, using 3-digit alphanumeric codes. Focussing on common items like metadata and location.