Template:Single chart/doc

This template is used to cite sources in Wikipedia. It is specifically for recorded musical single releases: singles. A similar template for use when citing sources for musical albums can be found at Template:Album chart; however, for EPs or other releases, it has not yet been developed.

In general, the template expands to produce a table row with the information country, record chart, reference, and peak position for the given single on the particular chart. Tables of such information are commonly used in Wikipedia articles on singles, albums, discographies and artists.

This template does not verify any positions or chart appearances. It primarily provides a reference URL believed to be associated with a reliable source for a recognised chart. The reference URL itself is also not checked. Entering an incorrect or alternative spelling of a song title can produce a bad link, for example. Individual editors will need to follow the URLs generated by the template to verify their usefulness before walking away from an edited article.

Usage
This template outputs data suitable for inclusion within a record chart table. It will produce a referenced chart name and a position. It can be used as a part of a larger table, or a series of cells can be used to create a chart. This template does not create the surrounding table markup.

All field names used must be in lowercase.

You can copy a blank version to use. Remember to use the "|" (pipe) character between each field. Please delete any unused fields to avoid clutter in the edit window.

The template has the following syntax:

Fields
The parameters publish-date, access-date, and refname are optional. Whether the other parameters are required or not depend on the chart being referenced. See the tables in the Support section below.
 * (Chart identifier) (or first parameter, without name): Chart identifier. Must be one of the options listed under Chart ID in the tables of the Support section below. Often named as a country or nationality (e.g., Spain or Spanish), but sometimes named for a specific chart (e.g., Billboardjapanhot100). Some charts allow more than one identifier; the results produced are identical.
 * (Peak position) (or second parameter, without name): The number you found to be the peak position achieved by the single on the specific chart to date. If the song has not appeared on the chart (due to low popularity or lack of release in a country), you can enter a dash (–, not a hyphen -). Usually, it's better to omit the template completely.
 * song: Title of the single. Made-up words, slang, "hip" spellings, tricky punctuation, etc., can make this parameter difficult to correctly determine. Make sure to check the resulting reference URL (Preview) before saving the definitive version of the article.
 * songid: Numeric identifier used by some chart listings (see CIS below). Determined by performing a search at the chart listings' website for the single, The songid can be found in the Web address (URL) by inspection. For example, the page for "In My Mind" at tophit.ru has the URL https://tophit.ru/ru/tracks/88003/, so the songid to use is 88003.
 * id: Obsolete. Used in some cases in the same manner songid is used
 * artist: Name of the single's performer. As for the song parameter, odd spellings and clever stylings (e.g., Ke$ha) can make this parameter difficult to correctly determine. The German chart, for example, typically requires names in lastname,firstname format. Make sure to check the resulting reference URL (Preview) before saving the definitive version of the article. Also note that this parameter is required for all charts where you are reusing the references using the default naming (see Output section below). If you use the refname parameter, however, artist may not be absolutely necessary.
 * artistid: Numeric identifier used by some chart listings (see UKsinglesbyname below). Determined by performing a search at the chart listings' website for the artist, The artistid can be found in the Web address (URL) by inspection. For example, the page for Madonna at www.officialcharts.com has the URL https://www.officialcharts.com/artist/28948/madonna/, so the artistid to use is 28948.
 * chartid: Numeric identifier used by some chart listings, see support below
 * url: The URL of the reference where you found the song's peak position for the chart. Used only for particular charts (see Support tables) where there is no indexing system, not necessary (or even used) for others.
 * urltitle: The title of the page for the reference where you found the song's peak position for the chart. Used in combination with the url parameter, and only for particular charts (see Support tables) where there is no indexing system, not necessary (or even used) for others.
 * date: Date of the chart in the format YYYYMMDD or another format specified, indicating year (Y), month (M) and day (D). Used only for certain charts; not necessary (or even used) for others. This date is used solely to create the reference URL to the download chart, and is not displayed textually in the references list. For general citation of any chart's publication date, use the optional publish-date parameter.
 * year: Four-digit year indicating the year being reported by the chart. Used in combination with the week parameter and only for certain charts; not necessary (or even used) for others. Not necessarily the same as the publication date referred to by publish-date.
 * week: Two-digit week indicating the week being reported by the chart. Week is a number from 01 to 53, with a leading 0 for weeks 01-09 (some charts do not require the leading zero; consult Support tables below). Used in combination with the year parameter and only for certain charts; not necessary (or even used) for others. Not necessarily related to the publication date referred to by publish-date.
 * note: For adding a note about a particular version of a song, e.g.,, or.
 * publish-date: Date of publication of the reference generated by the template, in the same format as other dates in citations in the same article. Optional parameter.
 * access-date: Date that the reference generated by the template was retrieved to determine peak position. Should be in the same format as other dates in citations in the same article. Optional parameter.
 * refname: Enables you to specify a name for the reference generated by the template. If no value is provided for refname the default reference name (in the form sc_Chartid_artist, see Output below) will be used. A reference with a name can be reused for claims elsewhere in the article. Optional parameter.
 * refgroup: Enables you to specify a name for the reference group. Optional parameter.
 * page: Used when referencing a book, see below where needed.

Template data
{	"description": "Creates a table row for a recognized single chart ", "params": { "1": {			"label": "Chart identifier", "description": "Chart name: recognized values are listed at Template:Single chart/doc", "type": "string", "required": true },		"2": {			"label": "Chart position", "description": "Peak position on the chart", "type": "number", "required": true },		"artist": { "label": "artist", "description": "Artist name as listed on the source chart", "type": "string", "required": true },		"song": { "label": "song", "description": "Song title as listed on the source chart", "type": "string", "required": true },		"refname": { "label": "reference name", "description": "Names the reference created by the template so that it may be used elsewhere in the article", "type": "string", "required": true },		"chartnote": { "label": "Notes", "description": "Any special notes about this version here. Typically used to distinguish versions, i.e. 'reggae mix' vs. 'dubsteb version'", "type": "string", "required": false },		"year": { "label": "year", "description": "Year in which the chart position occurred; format: yyyy; required for Czech Republic, all Hungarian charts, all Romanian charts, Ireland, Israeliairplay", "type": "number", "required": false },		"week": { "label": "week", "description": "Week number (1–53); required for Czech Republic, all Hungarian charts, all Romanian charts, Ireland, Israeliairplay", "type": "number", "required": false },		"url": { "label": "URL", "description": "Required for Bulgarian charts (must be from www.bamp-bg.org), and for Australiapandora (must be from pandora.nla.gov.au)", "type": "number", "required": false },		"publish-date": { "label": "date of publishing", "description": "Date of chart, as used in prose. Free-format date (using a format acceptable at MOS:DATE) indicating when the chart was released", "type": "string", "required": false, "aliases": [ "publishdate" ]		},		"date": { "label": "date", "description": "Date of chart, as used in a URL string. Required for Frenchdigital (format yyyymmdd with no spaces) or any UK chart (format yyyy-mm-dd )", "type": "number", "required": false },		"access-date": { "label": "access date", "description": "Free-format date (using a format acceptable at MOS:DATE) showing when this information was verified by an editor", "type": "string", "required": false, "aliases": [ "accessdate" ]		},		"rowheader": { "label": "Row header control", "description": "When set to true, the chart name will be treated as a row header", "type": "string", "required": false },		"refgroup": {}, "note": {}, "urltitle": {}, "page": {}, "chartid": {}, "songid": {}, "artistid": {}, "id": {} } }

Output
The template's expansion results in two output items:
 * a row of output for a two-cell table row, and
 * a reference

The output row includes the piping character to divide the left cell from the right cell. The left cell includes the country and/or chart name, with wikilinks to the chart article(s), as well as the reference note[n] as if it were enclosed in  tags. Any note included with the note parameter is shown in the left cell as well. The right cell contains the peak position number, including the code to horizontally center the number in the table cell.

The citation generated by this template will appear in the list in place of  or the  template, like any other references. The reference produced will be given a name in the form "sc_Chartid_artist" by default, i.e., if the article uses

then the citation could be used to support other statements on the page using a reference as in

Alternatively, the name can be overridden using the refname parameter, i.e.,

which could then be used as a citation to support other statements on the page using a reference as in

Note that the refname parameter does not require the use of quotation marks, but names with spaces in them will necessitate quotation marks in the name parameter of (for example, you would need to use  if you used spaces in the name).

Brief examples of output with different parameters
A few quick examples of template usage and the corresponding output are shown here. More detailed examples with surrounding table code are in the Examples with table layout section below.

{| class="wikitable" !scope="col"| Example no. !scope="col"| Coding (assumed inside a table row) !scope="col"| Output (assumed with
 * +Usage examples of Template:Single chart
 * style="width: 50%; vertical-align: top;" |
 * style="vertical-align: top;" |

Note the use of the  parameter to avoid causing a duplicate reference definition. the first number is the artistid and the second the songid. !scope="row"|New Zealand song !scope="row"|Norway song week year !scope="row"|Poland year !scope="row"|Poland2 !scope="row"|Polishdance !scope="row"|Portugal artist !scope="row"|Portugalairplay !scope="row"|Romaniaradioairplay week artist* !scope="row"|Romaniatvairplay !scope="row"|Russia artist* !scope="row"|Scotland artist song !scope="row"|Slovakia Slovakian week artist* !scope="row"|Slovakdigital !scope="row"|South Africa !scope="row"|South Africa2 !scope="row"|Spain Spanish song !scope="row"|Sweden Swedish song !scope="row"|Swiss Switzerland song !scope="row"|Swiss Romandy Romandy Suisse romande song !scope="row"|UK United Kingdom Main singles chart artist song !scope="row"|UKsinglesbyname Main singles chart song artistid !scope="row"|UKdance Dance singles chart artist song !scope="row"|UKdownload Download chart artist song !scope="row"|UKindependent UKindie Independent singles chart artist song !scope="row"|UKrandb R&B chart artist song !scope="row"|UKrock UKrockandmetal Rock and metal chart artist song !scope="row"|UKstreaming Streaming chart artist song !scope="row"|Ukraine artist* Other non-Billboard charts are not currently supported by and their use will need to be formatted and referenced manually (see the Brazil listing in Example 5 above). Be sure, however, not to use one of the deprecated charts.
 * style="vertical-align: top;" |
 * style="vertical-align: top;" |
 * style="vertical-align: top;" |
 * Recorded Music NZ
 * www.charts.nz
 * artist
 * VG-lista
 * http://lista.vg.no/
 * artist
 * When year and week are present, this form will provide a reference pointing to lista.vg.no/.
 * Polish music charts
 * http://bestsellery.zpav.pl/
 * chartid
 * Archived from March 2010 to December 2022. chartid is the end of the url for the chart, for example the chart of 25 December 2022 is at http://bestsellery.zpav.pl/airplays/top/archiwum.php?year=2022&idlisty=4318 so use 4318
 * Polish music charts
 * https://www.olis.pl/
 * date
 * From January 2023. Use date in the format DD.MM.YYYY.
 * Polish Dance Chart
 * http://ozz.zpav.pl/
 * chartid
 * Archived from April 2010 to August 2018. chartid is the end of the url for the chart, for example the chart of 16 November 2015 is at http://ozz.zpav.pl/muzykawbiznesie/toplistyprzebojow.php?idtypu=11&idlisty=1808 so use 1808
 * Associação Fonográfica Portuguesa
 * https://portuguesecharts.com/
 * song
 * Associação Fonográfica Portuguesa
 * https://www.audiogest.pt/
 * chartid
 * Archived from 2018. The value of chartid is the end of the url for the chart, for example for the 22 December 2022 chart is at https://www.audiogest.pt/uploads/files/file_2023-01-02-04-18-58.pdf so use file_2023-01-02-04-18-58.pdf
 * Romanian Radio Airplay Chart
 * rowspan="2"|mediaforest.ro
 * rowspan="2"|year
 * rowspan="2"|Year and week indicate the referenced chart. Week is a number from 01 to 53, with a leading 0 for weeks 01 to 09. To retrieve peak positions, the user may combine the "Romanian" and "International" columns by the number of broadcasts.
 * Romanian TV Airplay Chart
 * Tophit
 * tophit.ru
 * date
 * Date is formatted YYYY-MM-DD.
 * Official Charts Company
 * www.officialcharts.com
 * date
 * Date is formatted YYYYMMDD.
 * ČNS IFPI (Rádio Top 100)
 * rowspan="2"|www.ifpicr.cz
 * rowspan="2"|year
 * rowspan="2"|Year and week indicate the referenced chart. Week is a number from 01 to 53, with a leading 0 for weeks 01 to 09. A comment is generated in the reference to show what should be entered in the search table to produce the correct chart. Hitparadask contains Rádio Top 100 archives from 200635 to 201634 and Singles Digitál Top 100 archives from 201426 to 201634, while Hitparada contains Rádio Top 100 and Singles Digitál Top 100 archives from 201643 onwards.
 * ČNS IFPI (Singles Digitál Top 100)
 * EMA
 * www.sa-ema.com
 * date
 * Date is formatted YYYY-MM-DD
 * TOSAC
 * theofficialsacharts.co.za
 * year week
 * Only works correctly from 2022
 * PROMUSICAE
 * www.spanishcharts.com
 * artist
 * Sverigetopplistan
 * www.swedishcharts.com
 * artist
 * Schweizer Hitparade
 * www.swisscharts.com
 * artist
 * Media Control
 * lescharts.ch
 * artist
 * Official Charts Company
 * www.officialcharts.com
 * date
 * Date is formatted YYYYMMDD.
 * Official Charts Company
 * www.officialcharts.com
 * artist
 * This accesses the artist information page on officialcharts.com.
 * Official Charts Company
 * www.officialcharts.com
 * date
 * Date is formatted YYYYMMDD.
 * Official Charts Company
 * www.officialcharts.com
 * date
 * Date is formatted YYYYMMDD.
 * Official Charts Company
 * www.officialcharts.com
 * date
 * Date is formatted YYYYMMDD.
 * Official Charts Company
 * www.officialcharts.com
 * date
 * Date is formatted YYYYMMDD.
 * Official Charts Company
 * www.officialcharts.com
 * date
 * Date is formatted YYYYMMDD.
 * Official Charts Company
 * www.officialcharts.com
 * date
 * Date is formatted YYYYMMDD.
 * Tophit
 * tophit.ru
 * date
 * Date is formatted YYYY-MM-DD.
 * }
 * }

* These charts require the artist parameter solely for the purposes of internal reference naming using the default format (see Output above). If you are using the refname parameter to override the default naming, or you are sure that the references are not being reused in the article, you omit artist for the marked charts. The use of song and title are recommended for all charts, however.

Billboard charts
Billboard charts all require the artist name. Other Billboard charts are not currently supported by and their use will need to be formatted and referenced manually (see the Brazil listing in Example 5 above). Be sure, however, not to use one of the deprecated charts.

Example with dummy data
Since this template produces only individual rows within a table, you will need to add (or already have) the table's framework in the article. Here is a sample table with its corresponding output:

Expands into:

Expands into:

Maintenance categories
To help maintain music articles, this template will automatically categorize articles that call it based on the parameters used in the reference.

Single chart used with missing parameters
contains a list of articles that have failed error checking because of missing parameters.

Single chart usages for chartname
This set of categories lists the calls for each possible chart name, i.e. contains all articles that have used the template to build a reference for the Billboard Hot 100. Note that alternate names are not handled gracefully: and  are separate categories.