HXL hashtag dictionary

Release 1.0 final, 2016-03-18 (permalink, previous version)

This document 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, then include the spreadsheet data afterwards. For more information about using HXL hashtags and attributes, please see HXL tagging conventions.

You can make up your own hashtags like #x_toxicity if you cannot find what you need here: see Creating extension tags for more information.

  1. Core HXL hashtags
  2. Suggested attributes
  3. Changes from previous versions

1. Core HXL hashtags

(A cheatsheet of these hashtags is also available on a 4×6 in / 10×15 cm postcard.)

This section lists the suggested core HXL hashtags grouped into five topic areas:

1.1. Places

Hashtag Description Suggested attributes
#region Supra- or cross-national region (e.g. Sahel, Horn of Africa, Caribbean). +name, +code, +type
#country Country (often left implied in a dataset). +name, +code, language attributes like +ar
#adm1 Top-level subnational administrative area (e.g. a governorate in Syria). +name, +code, language attributes like +en
#adm2 Second-level subnational administrative area (e.g. a municipio in Colombia). +name, +code, language attributes like +ru
#adm3 Third-level subnational administrative area (e.g. a subdistrict in Afghanistan). +name, +code, language attributes like +tl
#adm4 Fourth-level subnational administrative area (e.g. a barangay in the Philippines). +name, +code, language attributes like +fr
#adm5 Fifth-level subnational administrative area (e.g. a ward of a city). +name, +code, language attributes like +dz
#loc Any point location, such as a village, camp, or clinic. +name, +code, +type, language attributes like +id
#geo Geodetic geometry information (points, lines, shapes). Use for latitude and longitude, as well as bounds information. +lat, +lon, +elevation, +border, +bounds, +url (to link to external boundary/shape data, generally in GeoJSON format).

1.2. People and households

Hashtag Description Suggested attributes
#affected Number of people or households affected by an emergency. +num, +type, SADD attributes like +f, impact attributes like +idps, +label
#beneficiary Beneficiary information. +num, +type, SADD attributes like +elderly, impact attributes like +displaced, +label
#inneed Number of people or households in need of assistance. +num, +type, SADD attributes like +children, impact attributes like +injured, +label
#population Population characteristics. +num, +type, SADD attributes like +m, impact attributes like +infected, +label
#reached Number of people or households reached with assistance. +num, +type, SADD attributes like +infants, impact attributes like +noncamp, +label
#targeted Number of people or households targeted for assistance +num, +type, SADD attributes like +adolescents, impact attributes like +incamp, +label

1.3. Responses and other operations

Hashtag Description Suggested attributes
#activity Programme, project, or other activity description +name, +code, +type, +project, +programme
#capacity The response capacity of the entity being described (e.g. "25 beds"). +text, +num, +type, +label
#contact Contact information for the subject of a data record (e.g. an activity). +name, +email, +phone, +address, +role, +url, language attributes like +es, +label
#indicator A formal indicator being tracked. +name, +code, +type, language attributes like +pt
#operations Information that affects humanitarian operations, such as a restriction on movement or road closure. +text, +code, +restriction, +access, +quarantine, +label, language attributes like +ms
#org An organisation contributing to a humanitarian emergency response, e.g. a local government, community-based organisation, NGO, agency, donor, or law-enforcement or military unit. Use #group for organisations that are not part of the emergency response (e.g. a paramilitary group). +name, +code, +funder, +prog, +impl, +ngo, language attributes like +fa
#output An output indicator (e.g. “number of water-purification kits distributed”). +text, +code, +num, +outcome, +type, language attributes like +ar
#sector A humanitarian cluster or sector. For a formal cluster, use with the +cluster attribute (#sector+cluster). +name, +code, +cluster, language attributes like +fr
#subsector A humanitarian subsector. +name, +code, language attributes like +es

1.4. Crises, incidents, and events

Hashtag Description Suggested attributes
#cause The cause of an event. +text, +code, +type, language attributes like +fr
#crisis A humanitarian emergency. For the values under #crisis+code, the GLIDE number is recommended. +name, +code, +type, language attributes like +ar
#event An individual event or incident within a crisis/emergency, such as a (localised) flood, bridge collapse, or conflict. +text, +code, +type, language attributes like +ru
#group A group (of any type) related to humanitarian crisis (e.g., a paramilitary group) Use #org for an organisation, such as an NGO, contributing to the humanitarian response, and #population for a collection of people in need of assistance. +name, +code, +type, +combatant, language attributes like +tl
#impact The impact of a crisis on a group or other entity. +text, +code, +type, language attributes like +en
#severity The severity of an event. +text, +code, +type, language attributes like +es

1.5. Metadata

Hashtag Description Suggested attributes
#date Date when the date in the record applies. Preferred format is ISO 8610 (e.g. “2015-06-01”, “2015-Q1”, etc.) +start, +end, +reported, +verified, +approved, +occurred (etc.).
#description Long description for a data record. +summary, +title, +notes, +caveats, +methodology, language attributes like +ar
#meta Metadata about a row. +url, +source, +provenance, +verified, +reliability, +count, +sum, +average, +min, +max (etc.).
#status Project/activity status description (such as “planned”, “active”, “canceled”, or “complete”). +text, +code

2. Suggested attributes

This section contains some suggested attributes for HXL hashtags, to add extra information to hashtags. You are free to use whatever attributes you wish, as long as they meet the syntactic requirements; however, using the suggested attributes here will help to make your data more interoperable.

2.1. Sex- and-age disaggregation (SADD) attributes

Sex- and age-disaggregated data (SADD) is an important part of many humanitarian datasets (see Why Age and Sex Matter for more background). Age categories, in particular, tend to vary from country: these attributes don’t try to capture the precise differences (e.g. does adolescence end at 16 or 18?), but rather, to provide a loose level of interoperability (e.g. are we talking about younger people or adults?).

You may create additional attributes to make more-precise distinctions: for example, if a column were related the the number of girls from 5–12 affected by the crisis, you could use the hashtag/attribute combination #affected +f +children +age_5_12 to provide increasingly-detailed information (recipients who do not understand the custom +age_5_12 attribute would simply ignore it).

Attribute Description Sample hashtags
+f The hashtag applies to female persons. #targeted+f (number of females targeted for assistance), #reached+f+infants (number of baby girls reached with assistance)
+m The hashtag applies to male persons. #targeted+m (number of males targeted for assistance), #reached+m+elderly (number of elderly men reached with assistance)
+i The hashtag applies to persons who don’t identify as male or female ( such as intersex, bigender, gender fluid, or non-gendered). #inneed+i (number of intersex people in need of assistance)
+infants The hashtag applies to infant children (precise age range varies). #affected+infants (number of infants affected), #inneed+m+infants (number of baby boys in need of assistance)
+children The hashtag applies to non-adults (precise age range varies; may also imply +infants and/or +adolescents). #affected+children (number of children affected), #inneed+f+children (number of girls in need of assistance)
+adolescents The hashtag applies to adolescents (precise age range varies). #targeted+adolescents (number of adolescents targeted for assistance), #inneed+m+adolescents (number of adolescent boys in need of assistance)
+adults The hashtag applies to adults (precise age range varies; may also imply +elderly). #targeted+adults (number of adults targeted for assistance), #inneed+f+adults (number of adult women in need of assistance)
+elderly The hashtag applies to elderly people (precise age range varies). #reached+elderly (number of elderly adults reached with assistance), #affected+displaced+elderly (number of elderly adults displaced from their homes)

2.2. Language attributes

Some humanitarian datasets combine information in multiple languages (e.g. Pashto and Dari in Afghanistan). The HXL standard suggests reserving all two-character attributes for use as language codes, e.g. +ar for Arabic, +es for Spanish, +en for English, and +fr for French. You can then use those attributes to disambiguate columns with equivalent text in different languages, e.g. #description+fa for Dari and #description+ps for Pashto. For more information, see Attributes for languages.

2.3. Classification attributes

These attributes modify tags to provide classification information.

Attribute Description Sample hashtags
+code A machine-readable code or identifier. #adm2+code (an administrative level-two P-code), #loc+type+code (a classification code for a location type)
+type The category of thing being description. #loc+type (location type, e.g. “camp”, “hospital”), #org+type+code (classification code for an organisation type)

2.4. Geographical attributes

These attributes are all for use with the #geo tag.

Attribute Description Sample hashtags
+lat A latitude, preferably in decimal degrees. #geo+lat
+lon A longitude, preferable in decimal degrees. #geo+lon
+coord Latitude and longitude together in the same column, separated by a comma or space. #geo+coord
+elevation An elevation above mean sea level, preferably in metres. #geo+elevation
+bounds Boundary data for an area (e.g. a GeoJSON shape file). Combine with +url to point to the data stored elsewhere. #geo+bounds+json (inline GeoJSON boundary data), #geo+bounds+url (link to external boundary data).

2.5. Date attributes

These attributes are for use mainly with the #date hashtag.

Attribute Description Sample hashtags
+start An actual or planned starting date, e.g. for an activity. #date+start
+end An actual or planned ending date, e.g. for an activity. #date+end
+reported The date when a row of HXL data was reported. #date+reported
+approved The date when an activity or other action was approved. #date+approved
+canceled The date when an activity or other action was canceled. #date+canceled
+occurred The date when an event took place. #date+occurred

2.6. Impact attributes

These attributes refine tags like #affected to specify different kinds of impacts.

Attribute Description Sample hashtags
+injured The hashtag refers to those physically injured (but not killed) as a result of the crisis. #reached+injured (number of injured people reached with humanitarian assistance)
+killed The hashtag refers to those killed as a result of the crisis. #affected+elderly+killed (number of elderly people killed)
+infected The hashtag refers to those infected with disease as a result of the crisis. #targeted+infected (number of infected people targeted for assistance)
+displaced The hashtag refers to those displaced from their homes by the crisis. #affected+displaced (number of displaced people)
+refugees The hashtag refers to those displaced to other regions or countries. #inneed+refugees (number of refugees in need of assistance)
+idps The hashtag refers to those displaced internally. #affected+f+idps (number of female IDPs)
+incamp The hashtag refers to those displaced into official camps. #reached+incamp (number people reached with assistance in IDP or refugee camps)
+noncamp The hashtag refers to displaced people hosted outside of official camps. #inneed+noncamp (number of people in need of assistance outside of camps)

2.7. General attributes

Attribute Description Sample hashtags
+label Indication that the text header is a label for series data. See “Wide” (series) data for more information. #affected+label (the text header labels the series, e.g. “2014”, “2015”)
+name The hashtag refers to a human-readable name or title that commonly refers to the thing being description (a specialisation of +text). #org+name (the name of an organisation)
+num The hashtag refers to a numeric value (where there might otherwise be ambiguity). #output+num (number of items delivered or produced.)
+text The hashtag refers to a human-readable text version of the information (+name is a specialisation of +text). #output+text (description of the items produced or delivered)
+url Column contains web links, such as “http://example.org/something” #geo+bounds+url (link to boundary data)
+source Used with the #meta to indicate the original data source. #meta+source+url (link to the source’s web site)

3. Changes from Previous versions

Changes from HXL 1.0 beta to HXL 1.0 final:

  • Added the new #event and #group hashtags.
  • No longer list data types for hashtags (since the attributes can change the suggested type).
  • Some clarifications and examples in descriptions.
  • Minor changes to suggested attributes (non-normative):

    • Suggest the use of the +text or +name attributes (as appropriate) when hashtags can sometimes refer to human-readable descriptions (e.g. #sector+name vs +sector+code).
    • Suggest GeoJSON format for the content of #geo+bounds
    • Suggest +type as a possible attribute for #affected
    • Suggest impact attributes for #beneficiary, #inneed, #population, #reached, and #targeted
    • Suggest language attributes for #contact, #indicator, and #operations
    • Suggest +occurred as a possible attribute for #date
    • Suggest +reliability, +count, +sum, +average, +min, and +max as additional possible attributes for #meta
    • Added +label.

Changes from HXL 1.0 alpha to HXL 1.0 beta:

  • Hashtags removed: #activity_id, #adm, #adm1_id, #adm2_id, #adm3_id, #adm4_id, #adm5_id, #aff_num, #age, #age_id, #agesex, #agesex_id, #beneficiary_id, #country_id, #crisis_id, #crisis_lnk, #data_lnk, #datatype, #datatype_id, #delivered_num, #email, #females_num, #from_date, #funder, #funder_id, #households_num, #idp_num, #impact1, #impact1_id, #impact2, #impact2_id, #impact3, #impact3_id, #impl, #impl_id, #injured_num, #inneed_num, #lat_deg, #loc_id, #loctype, #loctype_id, #lon_deg, #males_num, #method, #method_id, #method_lnk, #name, #org_id, #origin, #origin_id, #output_id, #people_num, #period_date, #phone, #prog, #prog_id, #reached_num, #refugee_num, #region_id, #report_date, #sector_id, #sex, #sex_id, #shelter1, #shelter1_id, #shelter2, #shelter2_id, #source, #source_id, #status_id, #subsector_id, #targeted_num, and #to_date
  • Hashtags added: #affected, #capacity, #cause, #contact, #date, #description, #geo, #impact, #indicator, #inneed, #meta, #operations, #output, #population, #reached, #severity, and #targeted
  • Added hashtag attributes to the standard.