HXL hashtag dictionary, version 1.0 beta

Release 1.0 beta, 2015-06-04 (previous version)

Permalink

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.

  1. Core HXL hashtags
  2. Suggested attributes
  3. Changes from HXL 1.0 alpha

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: Places; People and households; Responses and other operations; Crises, incidents and events; and general metadata.

1.1. Places

Tag Data type Description Suggested attributes
#region text Supra- or cross-national region (e.g. Sahel, Horn of Africa). +code (P-code), +type
#country text Country (often left implied in a dataset). +code (P-code), language attributes like +ar
#adm1 text Top-level subnational administrative area (e.g. a governorate in Syria). +code (P-code), language attributes like +en
#adm2 text Second-level subnational administrative area (e.g. a municipio in Colombia). +code (P-code), language attributes like +ru
#adm3 text Third-level subnational administrative area (e.g. a subdistrict in Afghanistan). +code (P-code), language attributes like +tl
#adm4 text Fourth-level subnational administrative area (e.g. a barangay in the Philippines). +code (P-code), language attributes like +fr
#adm5 text Fifth-level subnational administrative area (e.g. a neighbourhood of a city). +code (P-code), language attributes like +dz
#loc text Any point location, such as a village, camp, or clinic. +code (P-code), +type, language attributes like +id
#geo text 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).

1.2. People and households

Tag Data type Description Suggested attributes
#affected number Number of people or households affected by an emergency. +num (numeric value), SADD attributes like +f, impact attributes like +idp, +label
#beneficiary text Beneficiary description +num, +type, SADD attributes like +elderly, +label
#inneed number Number of people or households in need of assistance. +num, +type, SADD attributes like +children, +label
#population text Population characteristics. +num, +type, SADD attributes like +m, +label
#reached number Number of people or households reached with assistance. +num, SADD attributes like +infants, +label
#targeted number Number of people or households targeted for assistance +num, SADD attributes like +adolescents, +label

1.3. Responses and other operations

Tag Data type Description Suggested attributes
#activity text Project/activity description +code, +type, +project, +programme
#capacity text Description of the response capacity of the activity being described (e.g. "25 beds"). +num (for a numeric value), +type, +label
#contact text Contact information for the subject of a data record (e.g. an activity). +name, +email, +phone, +address, +role, +label
#indicator text Description of a formal indicator being tracked. +code, +type,
#operations text Description of a restriction on movement or other activities. +restriction, +access, +quarantine, +label, language attributes like +ms
#org text Organisation description +code, +funder, +prog, +impl, +ngo, language attributes like +fa
#output text Output indicator description +code, +num (for a numeric value), +outcome, +type
#sector text Sector/Cluster description +code, +cluster, language attributes like +fr
#subsector text Subsector description +code, language attributes like +es

1.4. Crises, incidents, and events

Tag Data type Description Suggested attributes
#cause text Description of the cause of an event. +code, +type, language attributes like +fr
#crisis text Crisis description +code, +type, language attributes like +ar
#impact text Description of the impact of a crisis on a group or other entity. +code, +type, language attributes like +en
#severity text Description of the severity of an event. +code, +type, language attributes like +es

1.5. Metadata

Tag Data type Description Suggested attributes
#date 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, …
#description text Long description for a data record (not to be confused with notes). +summary, +title, language attributes like +ar
#meta text Metadata about a row. +url, +source, +provenance, +verified, …
#status text Project/activity status description +code

2. Suggested attributes

This section contains some suggested attributes for HXL 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, especially since the 2004 Tsunami (see Why Age and Sex Matter for more background). Age categories, in particular, tend to vary from country: these tags 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. You may create additional tags to make more-precise distinctions.

Attribute Description Sample tags
+f The tag applies to female persons. #targeted+f (number of females targeted for assistance), #reached+f+infants (number of baby girls reached with assistance)
+m The tag applies to male persons. #targeted+m (number of males targeted for assistance), #reached+m+elderly (number of elderly men reached with assistance)
+i The tag applies to persons who don’t identify as male or female (sometimes called “intersex”). #inneed+i (number of intersex people in need of assistance)
+infants The tag 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 tag 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 tag 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 tag 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 tag 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. More information here.

2.3. Classification attributes

These attributes modify tags to provide classification information.

Attribute Description Sample tags
+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 tags
+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 tags
+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

2.6. Impact attributes

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

Attribute Description Sample tags
+injured The tag 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 tag refers to those killed as a result of the crisis. #affected+elderly+killed (number of elderly people killed)
+infected The tag refers to those infected with disease as a result of the crisis. #targeted+infected (number of infected people targeted for assistance)
+displaced The tag refers to those displaced from their homes by the crisis. #affected+displaced (number of displaced people)
+refugees The tag refers to those displaced to other regions or countries. #inneed+refugees (number of refugees in need of assistance)
+idps The tag refers to those displaced internally. #affected+f+idps (number of female IDPs)
+incamp The tag refers to those displaced into official camps. #reached+incamp (number people reached with assistance in IDP or refugee camps)
+noncamp The tag 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 tags
+num Tag refers to a numeric value (where there might otherwise be ambiguity). #output+num (number of items delivered, etc.)
+url Column contains web links, such as “http://example.org/something” #geo+bounds+url (link to boundary data)
+source Used to #meta to indicate the original data source. #meta+source+url (link to the source’s web site)

3. Changes from 1.0 alpha

The following hashtags from HXL 1.0 alpha were removed in 1.0 beta: #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 #to_date

The following hashtags not in HXL 1.0 alpha were added to 1.0 beta: #affected #capacity #cause #contact #date #description #geo #impact #indicator #inneed #meta #operations #output #population #reached #severity #targeted

All attributes are new in 1.0 beta.

7 thoughts on “HXL hashtag dictionary, version 1.0 beta

  1. Pingback: Humanitarian Exchange Language: a simple standard for messy data | Badili

  2. Pingback: Humanitarian Exchange Language - BI4NGOs

  3. Pingback: HDX | HXL 1.0 Beta Release: A simple standard for messy data

  4. Devin

    NGOs and government agencies often provide services to populations in crisis. 3W reports usually mention these services, but often don’t provide the level of specificity needed to enable (1) humanitarian aid workers and volunteers to make accurate referrals to survivors, (2) survivors to find actionable information about services they need, (3) humanitarian service providers to effectively plan their provisioning of services.

    I propose adding #service to HXL as a part of 1.3 “Responses and other operations”.

    The additional row that I propose including is below:

    #service – text – brief explanation of the assistance provided to people – +description (longer explanation), +name, +type, +status, +language, +eligibility (who can access this service), +schedule (days and hours this service is available), +process (documents and steps needed to access this service).

  5. Pingback: HDX | How HXL is being used at the British Red Cross

  6. Pingback: Humanitarian Exchange Language: a simple standard for messy data - International Open Data Conference 2016

  7. Pingback: Humanitarian Exchange Language: a simple standard for messy data - International Open Data Conference 2016

Comments are closed.