NCBI Bookshelf. A service of the National Library of Medicine, National Institutes of Health.
LinkOut Help [Internet]. Bethesda (MD): National Center for Biotechnology Information (US); 2006-.
LinkOut is a service of NCBI that allows third parties to link specific NCBI database records to relevant Web-accessible resources. Typically, publishers and other full-text providers use LinkOut to provide links from PubMed records to their online full-text journals.
How It Works
LinkOut provides links from PubMed and other NCBI database records to online resources external to the NCBI network. All linking information is submitted by LinkOut providers - the owner or agent for the owner of the online resource. LinkOut providers are responsible for maintaining their links.
To submit links to your resource, you will need to upload two files: an XML identity file and a resource file, which can be provided in either XML or CSV formats. The identity file contains the information about your organization, which is needed to list your resource in the LinkOut database. The resource file describes the PubMed records you will link from and contains the information that LinkOut needs to generate the links.
Prerequisites for Participation
- 1.
Journals must be included in PubMed for links to be created in PubMed citations. LinkOut works with two journal citation data sources: Journals indexed for MEDLINE and journals selected for full text deposit in PMC. To be included in MEDLINE, a journal must go through the MEDLINE selection process, see the details at:
- a.
https://www
.nlm.nih.gov /medline/medline_how_to_include.html - b.
https://www
.nlm.nih.gov /medline/medline_journal_selection .html - c.
To be included in PMC, a journal must go through the PMC selection process, see details at: https://pmc
.ncbi.nlm .nih.gov/pub/journalselect/
- 2.
Publishers of journals included in PubMed should submit their citation data electronically before submitting links to online full text. See PubMed’s Information for Publishers for details on submitting electronic data to PubMed.
- 3.
When a publisher submits links data without sending electronic citation data, links will be shown only under the PubMed “LinkOut more resources” drop-down menu. The publisher’s icon will not appear by default in PubMed’s Abstract and Records displays unless full text is freely available.
- 4.
Full-text providers that restrict access to full text may provide links to summary pages, provided that a link to the full text is prominently displayed on the summary page. In this case, providers should use one of the full-text attributes to inform users that full text is available.
For more information, see the Guidelines for Evaluation of Resources.
Apply for Inclusion in LinkOut
To apply for inclusion in LinkOut, send an email to vog.hin.mln.ibcn@tuoknil with the following information included:
- Name, email address, and phone number of a contact person in your organization.
- Your account name, if your organization currently provides electronic citation data to NCBI.
- The scope of your resource. Publishers should provide journal titles and ISSNs; journal aggregators may provide a description of their collection.
- Describe any restrictions on access to full text.
File Preparation: Identity File
The identity file contains the information needed to list a provider in LinkOut. This file must be named providerinfo.xml; the file name is case sensitive. The file should be composed in a text editor, such as NotePad, not in a word processing program.
The following is an example providerinfo.xml file for the LinkOut participant, Good Publisher, Inc. with Provider Id 8888 and NameAbbr GoodPublisher.
<?xml version="1.0"?>
<!DOCTYPE Provider PUBLIC "-//NLM//DTD LinkOut 1.0//EN"
"https://www.ncbi.nlm.nih.gov/projects/linkout/doc/LinkOut.dtd">
<Provider>
<!-- ProviderId is assigned by NCBI -->
<ProviderId>8888</ProviderId>
<Name>Good Publisher, Inc.</Name>
<NameAbbr>GoodPublisher</NameAbbr>
<SubjectType>publishers/providers</SubjectType>
<Attribute>subscription/membership/fee required</Attribute>
<!-- Url is used in My NCBI and the LinkOut Journals and Providers lists -->
<Url>http://www.goodpublisher.com</Url>
<!-- Brief is used in My NCBI -->
<Brief>
An international publisher of biomedical journals and books
</Brief>
</Provider>
<SubjectType> and <Attribute> elements included in the providerinfo.xml file will apply to all links submitted by the provider. In the example above, a subscription is required to access all full text at the provider’s site, therefore <Attribute>subscription/membership/fee required</Attribute> has been included in the providerinfo.xml file.
File Preparation: Resource XML File
The resource file describes the PubMed records to which your links to the article full text will be applied and contains the information that LinkOut needs to generate the URLs. Links described in the resource file must link directly to the full text, requiring no additional searching after a user clicks on the provider’s link.
Resource files must have a file extension .xml; the file extension is case sensitive. File names may contain alpha-numeric characters and underscores only. Special characters and spaces are not allowed. Typically, files are named journals.xml, or journaltitle.xml. To help with file management, a provider may submit more than one resource file.
This file should be composed in a text editor, such as NotePad, not in a word processing program.
Section Contents
Resource File XML Format
The resource file below describes links to Web-accessible full text for the journal J Cell Biol. Full text is provided by Good Publisher, Inc., ProviderId 8888.
<?xml version="1.0" ?>
<!DOCTYPE LinkSet PUBLIC "-//NLM//DTD LinkOut 1.0//EN"
"https://www.ncbi.nlm.nih.gov/projects/linkout/doc/LinkOut.dtd"
[<!ENTITY icon.url "https://www.goodpublisher.com/icon/goodpublisher.jpg">
<!ENTITY base.url "https://www.goodmedical.org/cgi/content/" > ]>
<LinkSet>
<Link>
<LinkId>1</LinkId>
<ProviderId>8888</ProviderId>
<IconUrl>&icon.url;</IconUrl>
<ObjectSelector>
<Database>PubMed</Database>
<ObjectList>
<Query> "J Cell Biol" [ta] AND 1997/06/15:2010[dp]</Query>
</ObjectList>
</ObjectSelector>
<ObjectUrl>
<Base>&base.url;</Base>
<Rule>&lo.issn;/&lo.vol;/&lo.page;</Rule>
<Attribute>full-text online</Attribute>
</ObjectUrl>
</Link>
</LinkSet>
<ObjectList>: Selecting Records in a Resource File
The <ObjectList> element is used to select the NCBI database records to which links will be applied. <ObjectList> contains one or more <Query> elements OR one or more <ObjId> elements. <Query> elements contain a valid PubMed search that will retrieve the records to which the link described in <ObjectUrl> will be applied. <ObjId> elements contain the Unique Identifier (PMID) for records to which the link described in <ObjectUrl> will be applied.
Selecting Records Using <ObjId>
<ObjId> contains the PubMed ID (PMID) for a single PubMed record.
| Example: Select record with PMID 9679140 |
|---|
| <ObjectList> <ObjId>9679140</ObjId> </ObjectList> |
More than one <ObjId> can be used in an <ObjectList>.
| Example: Select records with PMIDs 9679140 and 12589072 |
|---|
| <ObjectList> <ObjId>9679140</ObjId> <ObjId>12589072</ObjId> </ObjectList> |
Because <ObjId> requires more maintenance than <Query>, NCBI recommends using <Query> whenever possible. When <ObjId> is used, the provider is responsible for updating the resource file as new records are submitted to PubMed.
Selecting Records Using <Query>
The <Query> element must contain a valid PubMed search. Note that all components of a query would need to be valid for links to be created.
Tips for using <Query>
- 1.
Use either NLM’s Title Abbreviations [ta] or ISSN numbers in journal searches. Title Abbreviations must be entered in double quotes, e.g., “J Mol Dis” [ta].
- 2.
Include the date range for full text. Use this format: startyear:endyear[dp]. Dates should be notated as YYYY/MM/DD. Month and Day are optional.
- 3.
Ranging is not allowed in Volume, Issue, Page, or PMID searches.
- 4.
Truncation (wildcards such as *) is not allowed in search statements.
- 5.
Search field tags must be enclosed in square brackets.
- 6.
To apply a rolling embargo to records included in or excluded from a query, use “last x (day|weeks|months|years)”[dp] to select records based on the time period indicated. Dates are calculated as follows: 1 week = 7 days, 1 month = 30 days, 1 year = 365 days.
- 7.
Do not use the search field tags [sb] of [filter]. The only exception is future [sb]. Future [sb] will include or exclude all citations with a publication date after today.
- 8.
Boolean operators AND, OR, NOT must be in uppercase.
Example: Select records for the journal “J Mol Dis” starting from the publication date, June 15, 1997. As new records are submitted to PubMed, links will be applied automatically. <ObjectList>
<Query> “J Mol Dis” [ta] AND 1997/06/15:2010 [dp]</Query>
</ObjectList>Example: Select records for the journal “J Mol Dis” written by J Smith. As new records are submitted to PubMed, links will be applied automatically. <ObjectList>
<Query> “J Mol Dis” [ta] AND Smith J [au] </Query>
</ObjectList>
More than one <Query> can be listed within the <ObjectList>, as shown in the Example below.
| Example: Select records for the journal “J Mol Dis” with a publication date from June 15, 1997 and records for the journal “J Feet” starting from January 1, 2000. As new records are submitted to PubMed, links will be applied automatically. |
|---|
| <ObjectList> <Query> “J Mol Dis” [ta] AND 1997/06/15:2010 [dp]</Query> <Query>”J Feet”[ta] AND 2000:2010[dp]</Query> </ObjectList> |
To apply a rolling embargo to records included in or excluded from a query, use “last x (weeks|months|year)”[dp] to select records based on the time period indicated.
| Example: Select records for the journal “J Mol Dis” with publication date June 15, 1997 to the date 6 months earlier than today. Links will not be applied to records published in the last 6 months. |
|---|
| <ObjectList> <Query> “J Mol Dis” [ta] AND 1997/06/15:2010 [dp] NOT “last 6 months”[dp]</Query> </ObjectList> |
Citation providers sometimes submit records for articles that have not yet been published. “last x (weeks|months|year)”[dp] is very literal and will only select or exclude records from the past. To exclude records with a publication date in the future, use future[sb].
| Example: Select records for the journal “J Mol Dis” with publication date 1997 to the present. Links will not be applied to records published in the last six months or with a future publication date. |
|---|
| <ObjectList> <Query> “J Mol Dis” [ta] AND 1997:2010 [dp] NOT “last 6 months”[dp] NOT future[sb]</Query> </ObjectList> |
Records may also be submitted to PubMed for “ahead of print” articles (articles that are available online before they are available in print). To select these records, use pubstatusaheadofprint.
| Example: Select ahead of print records for the journal “J Mol Dis”. |
|---|
| <ObjectList> <Query> “J Mol Dis” [ta] AND pubstatusaheadofprint</Query> </ObjectList> |
<ObjectUrl>: Specifying the Link to Access Online Full Text
The <ObjectURL> element is used to describe the link to the online resource. <ObjectURL> contains the sub-elements, <Base>, <Rule>, <SubjectType>, and <Attribute>. <Base> and <Rule> are concatenated to form the URL for the link. <SubjectType> and <Attribute> describe the resource to which the record is being linked.
Creating a URL for a Link
<Base> is the stable portion of the URL for the full text of the selected records. This is usually the URL of the provider’s web site or CGI program.
<Rule> is the remainder of the URL needed to access the online full text.
| Example: Create the URL https://www.goodmedical.com/articles.asp?AID=1988 |
|---|
| <Base>https://www.goodmedical.com/articles.asp?</Base> <Rule>AID=1988</Rule> |
If the URL for the full text follows a pattern using variable values that are found in the PubMed record, the pattern can be described in the <Rule> element and LinkOut can insert the appropriate values for each citation. This allows many links to be generated from the information in a single <ObjectUrl>.
URL patterns are described using LinkOut’s XML entities. An XML entity is a short text string that represents a type of value. During LinkOut processing, the text string is replaced in the URL by the appropriate value for each citation.
| Example: Create URLs following the pattern: https://www.goodmedical.org/cgi/full/id=[PMID] |
|---|
| <Base>https://www.goodmedical.org/cgi/full/</Base> <Rule>&lo.id;</Rule> |
| Example: Create URLs following the pattern: https://www.goodmedical.org/cgi/full/[ISSN]/[volume number]/[start page] |
|---|
| <Base>https://www.goodmedical.org/cgi/full/</Base> <Rule>&lo.issn;/&lo.vol;/&lo.page;</Rule> |
Entities can be combined with other information in the <Rule>.
| Example: Create URLs following the pattern: https://www.goodmedical.org/links/record/pmidlookup?view=reprint&pmid=[PMID of the record] |
|---|
| <Base>https://www.goodmedical.org/links/record/</Base> <Rule>pmidlookup?view=reprint&pmid=&lo.id;</Rule> |
LinkOut does not support Unicode (UTF-8) and requires that certain special characters be encoded in files.
Describing the Resource
The elements <SubjectType> and <Attribute> are used in the <ObjectUrl> to describe the resource to which records are being linked. Available SubjectTypes can be found in Special Elements: SubjectType. Available Attributes can be found in Special Elements: Attribute.
If the available SubjectTypes and Attributes do not suffice to describe the resource, UrlName can be used as well. If no SubjectType is given, the SubjectType “miscellaneous” will be assigned automatically.
As the availability and format of resources linked from NCBI database records should be readily apparent to users, links to online full text must be described using one of the following Resource Form Attributes:
<Attribute>full-text online</Attribute>
<Attribute>full-text PDF</Attribute>
<Attribute>full-text PostScript</Attribute>
In addition, if there are any barriers to accessing the full text, one of the following Barrier Attributes must be used:
<Attribute>registration required</Attribute>
<Attribute>subscription/membership/fee required</Attribute>
Continuing with the example above, if Good Medical, Inc. requires a subscription to access HTML full text, the <ObjectUrl> element might look like this:
<ObjectUrl>
<Base>https://www.goodmedical.org/cgi/full/</Base>
<Rule>&lo.issn;/&lo.vol;/&lo.page;</Rule>
<Attribute>subscription/membership/fee required</Attribute>
<Attribute>full-text online</Attribute>
</ObjectUrl>
Resource File Examples
Example 1: Dental Publications, Inc., Provider Id 1234, provides links from the PubMed records with PMIDs 98765432 and 87654321. URLs for the full text in PDF format are created using an internal identification number that is not included in PubMed, so links are created individually for each record. To minimize the repetition of textual data, the Icon URL and the Base URL have been defined as Entities in the Prolog of the file.
<?xml version="1.0"?>
<!DOCTYPE LinkSet PUBLIC "-//NLM//DTD LinkOut 1.0//EN"
"https://www.ncbi.nlm.nih.gov/projects/linkout/doc/LinkOut.dtd"
[<!ENTITY icon.url "https://www.dentalpub.com/images/fulltext.gif">
<!ENTITY base.url "https://www.dentalpub.com/Articles.asp?">]>
<LinkSet>
<Link>
<LinkId>1</LinkId>
<ProviderId>1234</ProviderId>
<IconUrl>&icon.url;</IconUrl>
<ObjectSelector>
<Database>PubMed</Database>
<ObjectList>
<ObjId>98765432</ObjId>
</ObjectList>
</ObjectSelector>
<ObjectUrl>
<Base>&base.url;</Base>
<Rule>AID=1988</Rule>
<Attribute>subscription/membership/fee required</Attribute>
<Attribute>full-text PDF</Attribute>
</ObjectUrl>
</Link>
<Link>
<LinkId>2</LinkId>
<ProviderId>1234</ProviderId>
<IconUrl>&icon.url;</IconUrl>
<ObjectSelector>
<Database>PubMed</Database>
<ObjectList>
<ObjId>87654321</ObjId>
</ObjectList>
</ObjectSelector>
<ObjectUrl>
<Base>&base.url;</Base>
<Rule>AID=1989</Rule>
<Attribute>subscription/membership/fee required</Attribute>
<Attribute>full-text PDF</Attribute>
</ObjectUrl>
</Link>
</LinkSet>
Example 2: Good Medical, Inc., Provider Id 4321, provides free online access to the publications Journal of Feet [ISSN 1234-5678] and Skin Graft International [ISSN 8765-4321] in HTML format. The URL to access online full text at their site follows this pattern for each article: https://www.goodmedical.org/cgi/full/[ISSN]/[volume number]/[start page]
<?xml version="1.0" ?>
<!DOCTYPE LinkSet PUBLIC "-//NLM//DTD LinkOut 1.0//EN"
"https://www.ncbi.nlm.nih.gov/projects/linkout/doc/LinkOut.dtd">
<LinkSet>
<Link>
<LinkId>1</LinkId>
<ProviderId>8888</ProviderId>
<IconUrl>https://www.goodmedical.org/icon/goodmedical.jpg</IconUrl>
<ObjectSelector>
<Database>PubMed</Database>
<ObjectList>
<Query>"J Feet" [ta] AND 1997/06/15:2010[dp]</Query>
<Query>"Skin Graft Int" [ta]</Query>
</ObjectList>
</ObjectSelector>
<ObjectUrl>
<Base>https://www.goodmedical.org/cgi/full/</Base>
<Rule>&lo.issn;/&lo.vol;/&lo.page;</Rule>
<Attribute>full-text online</Attribute>
</ObjectUrl>
</Link>
</LinkSet>
Example 3: A record may be retrieved by more than one <Query>. When this happens, link assignment will be handled as described in Duplicate Links and Multiple Links.
If these queries are in different Link elements, <Attribute>preference</Attribute> can be used to indicate which <Link> element should be applied to the record. This is generally used in situations where the links for a subset of a range have a different URL pattern or different access restrictions. See Duplicate Links and Multiple Links for more information.
In the example below, an article by J Smith in “J Mol Dis” published in 1998 will be retrieved by the <Query> statements in both LinkId 2 and LinkId 3.
The LinkOut provider Good Publisher, Inc. provides links to the full text of two of their journals, J Mol Dis and J Biol Chem.
LinkId 1 selects articles for PMID 9679140 and 9679141, a special case. The records are selected using <ObjId> and have a special <Rule>. They are available online in PostScript format; a subscription is required to access the full text. Because these records are also included in LinkId 3, <Attribute>preference</Attribute> is used to indicate that only this link should be applied to these citations.
LinkId 2 is for all articles authored by J Smith published in the journal J Mol Dis. These are freely available in PFD format. A special icon is used for these articles. Because these records are also included in LinkId 3, <Attribute>preference</Attribute> is used to indicate that only this link should be applied to these citations.
LinkId 3 applies to the remainder of the J Mol Dis articles and all J Biol Chem articles supplied by Good Publisher, Inc., where a subscription is required to access the full text. They are available in HTML format. This link will not be applied to the citations included in LinkId 1 and LinkId 2.
As both LinkId 1 and LinkId 2 describe specific requirements, they are listed before the general LinkId 3.
<?xml version="1.0"?>
<!DOCTYPE LinkSet PUBLIC "-//NLM//DTD LinkOut 1.0//EN"
"https://www.ncbi.nlm.nih.gov/projects/linkout/doc/LinkOut.dtd"
[ <!ENTITY icon.url "https://www.goodpublisher.com/icon/goodpublisher.jpg">
<!ENTITY base.url "https://www.goodmedical.org/cgi/content/" > ]>
<LinkSet>
<Link>
<LinkId>1</LinkId>
<ProviderId>8888</ProviderId>
<IconUrl>&icon.url;</IconUrl>
<ObjectSelector>
<Database>PubMed</Database>
<ObjectList>
<ObjId>9679140</ObjId>
<ObjId>9679141</ObjId>
</ObjectList>
</ObjectSelector>
<ObjectUrl>
<Base>&base.url;</Base>
<Rule>pmidlookup?view=reprint&pmid=&lo.id;</Rule>
<Attribute>full-text PostScript</Attribute>
<Attribute>subscription/membership/fee required</Attribute>
<Attribute>preference</Attribute>
</ObjectUrl>
</Link>
<Link>
<LinkId>2</LinkId>
<ProviderId>8888</ProviderId>
<IconUrl>https://www.goodpublisher.com/pubmed/smith.gif</IconUrl>
<ObjectSelector>
<Database>PubMed</Database>
<ObjectList>
<Query>"J Mol Dis" [ta] AND Smith J [auth]</Query>
</ObjectList>
</ObjectSelector>
<ObjectUrl>
<Base>&base.url;</Base>
<Rule>&lo.issn;/&lo.vol;/&lo.page;</Rule>
<Attribute>full-text PDF</Attribute>
<Attribute>preference</Attribute>
</ObjectUrl>
</Link>
<Link>
<LinkId>3</LinkId>
<ProviderId>8888</ProviderId>
<IconUrl>&icon.url;</IconUrl>
<ObjectSelector>
<Database>PubMed</Database>
<ObjectList>
<Query>"J Mol Dis" [ta] AND 1997:2010 [dp]</Query>
<Query>"J Biol Chem" [ta] AND 1996:2010[dp]</Query>
</ObjectList>
</ObjectSelector>
<ObjectUrl>
<Base>&base.url;</Base>
<Rule>&lo.issn;/&lo.vol;/&lo.page;</Rule>
<Attribute>full-text online</Attribute>
<Attribute>subscription/membership/fee required</Attribute>
</ObjectUrl>
</Link>
</LinkSet>
Linking with PII/DOI
PII and DOI are identifiers supplied by the publisher. PII is a Publisher Item Identification, assigned by the publisher for internal use. DOI is a Digital Object Identifier (more about DOI).
Links can be created using DOI or PII. Links will appear on all records in the <ObjectList> for which PII or DOI has been submitted by the publisher. NCBI does not input DOI or PII in PubMed records; to create links using PII or DOI, these values must be included when the record is submitted electronically. Publishers should submit PII/DOI for records ONLY if they will be used for linking.
To link using DOI/PII, identify a resolver that can locate the full text in the <Base> element and use the appropriate entity in the <Rule> element.
| Example |
|---|
| Retrieved record: Journal [ISSN 1234-5678]. 2004 Sep; 27(1):3-10 PMID: 98765432 DOI:10.1096/ajs59-5497 PII:12345678/2713 |
| Link using DOI: <Base>https://doi.org/</Base> <Rule>&lo.doi;<Rule> Resulting URL: https://doi.org/10.1096/ajs59-5497 |
| Link using PII: <Base>https://www.goodmedical.org/links/record/</Base> <Rule>&lo.pii;.php<Rule> Resulting URL: https://www.goodmedical.org/links/record/12345678/2713.php |
File Preparation: Resource CSV File
Links data can also be provided in CSV (comma separated values) files. The CSV resource file contains LinkOut data provider identifiers, PubMed citation Ids or queries, and links data from your journal site, all of which is used to create links in PubMed.
A LinkOut program converts CSV files in to XML files that validate against the LinkOut DTD. Links provided in CSV files must link directly from a PubMed citation to the corresponding article full text.
CSV files need to have the file extension .csv; the file extension is case sensitive. File names may contain alpha-numeric characters and underscores only. Special characters and spaces are not allowed. Examples of file name and extension: journaltitle_2vol.csv, or freearticles_Feb2015.csv, or fulltext_2_15.csv. To help with file management, a provider may submit more than one resource file. CSV files may not exceed 10 MB each.
Section Contents
Resource CSV File Data Fields
The CSV files used by LinkOut to create links in PubMed have required and optional data fields:
Field 1: PrId (required). Provider Id assigned by NCBI to links data providers. A four-digit number.
Field 2: DB (required). NCBI database name. Enter PubMed in this field.
Field 3: UID or Query (required). Each record in an NCBI database has a numerical unique identifier (UID). The unique identifier for PubMed citations is the citation PMID. For example, in this citation: https://www.ncbi.nlm.nih.gov/pubmed/24255994 the summary display lists the PubMed citation Id (PMID) below the article citation:
Genetic screening for PRA-associated mutations in multiple dog breeds shows that PRA is heterogeneous within and between breeds.
Downs LM, Hitti R, Pregnolato S, Mellersh CS.
Vet Ophthalmol. 2014 Mar;17(2):126-30. doi: 10.1111/vop.12122. Epub 2013 Nov 21.
PMID:24255994
Each PubMed record can also be retrieved using a query. For example, the above citation would be retrieved in PubMed using this query: “Vet Ophthalmol”[ta] AND 17[vol] AND 126[pg]
Field 4: URL (required). The URL to the article full text for a PubMed citation.
Filed 5: IconUrl (optional). URL of an icon file that you would like to represent your journal. The icon should meet the specifications described in Icons. The icon URL should point directly to the icon file in your server. If an icon is not provided, LinkOut will use the LinkOut generic icon.
Field 6: UrlName(optional). Additional description about the article link.
Field 7: SubjectType (required*). SubjectType is used to determine where links will be placed in the “LinkOut – more resources” display. In this field enter the subject type ‘publishers/providers.’ (*) If the ‘publishers/providers’ subject type is present in the identity file, this field should be left empty.
Field 8: Attribute (required). Enter “subscription/membership/fee required.” If the article full text is either free or open access enter either ‘Full-text online’ for the full text in HTML, or ‘Full-text PDF’ for the full text in PDF. Note that for article full text that requires a subscription, the attribute “Full-text online” or “Full-text PDF” must be listed in the identity file.
Resource File CSV Format
Your CSV file can be formatted as a table. Each field must be separated by commas. The CSV file format to create links in PubMed that lead to the article full text is the following:
Field 1: PrId. Provider Id, a four-digit number. For example: 1234.
Field 2: DB. Enter ‘PubMed’ in this field.
Field 3: Two options UID or Query:
UID. PubMed citation Id (PMID). For example: 11532607
Query. A query that leads to the PubMed record for an article: “Front Biosci”[ta] AND 6[vol] AND D1128[pg]
Field 4: URL. https://www.bioscience.org/2001/v6/d/highland/fulltext.htm
Filed 5: IconUrl. https://www.bioscience.org/images/medlink.jpg
Field 6: UrlName. Review article
Field 7: SubjectType. Publishers/providers (*) If the ‘publishers/providers’ subject type is present in the identity file, this field should be left empty.
Field 8: Attribute. Subscription/membership/fee required. Note that because the article full text is only available through subscription, the attribute “Full-text online” or “Full-text PDF” must be listed in the identity file. If this article were to be available free or open access, Field 8 would need to have either the attribute “Full-text online” or “Full-text PDF.”
When access to journal articles is available at the journal site in a combination of free, subscription only, or selected open access, provide separate CSV files for each. For example, links data to free articles would be provided separately from links data that is available through subscription only. Note that different icons can be provided for each type of link to display clearly in PubMed whether the article full text is available through subscription only, free, or open access.
Resource CSV File Examples
Example 1. Access to full text is through subscription, membership, or a fee is required: Provider Id 1234, provides links for the PubMed records PMIDs 11282572 and 11532607. URLs provided lead to the article full text in HTML. The icon URL leads to the icon file in jpeg format. The UrlName field is populated for the second article only (Review article). The subject type was provided in the identity file, and consequently this field is left blank. The articles are available through subscription only. In this case the Attribute field specifies that access to the article requires a subscription, since only one attribute can be used for each article entry, use the identity file to provide the article format: Full-text Online (HTML) or Full-text PDF.
Note that each field must be comma separated.
Field 1: PrId. 1234
Field 2: DB. PubMed
Field 3: UID. 11282572 and 11532607
Field 4: URL. https://www.bioscience.org/2001/v6/a/torshin/fulltext.htm and https://www.bioscience.org/2001/v6/d/highland/fulltext.htm
Filed 5: IconUrl. https://www.bioscience.org/images/medlink.jpg
Field 6: UrlName None and Review
Field 7: SubjectType. None (already present in the identity file)
Field 8: Attribute. Subscription/membership/fee required
A sample file using a spreadsheet program such as MS Excel.
| PrId | DB | UID | URL | IconUrl | UrlName | SubjectType | Attribute |
|---|---|---|---|---|---|---|---|
| 1234 | PubMed | 11282572 | https://www.bioscience.org/2001/v6/a/torshin/fulltext.htm | https://www.bioscience.org/images/medlink.jpg | Subscription/membership/fee required | ||
| 1234 | PubMed | 11532607 | https://www.bioscience.org/2001/v6/d/highland/fulltext.htm | https://www.bioscience.org/images/medlink.jpg | Review | Subscription/membership/fee required |
The same entries in a sample CSV file can be downloaded here. Save files with the extension .csv, and upload them to the “holdings” directory of the FTP assigned to you.
Example 2. Access to full text is free: Provider Id 1234, provides links for the PubMed records PMIDs 25588643 and 25588642, however, queries are used instead of PMID numbers. URLs provided lead to the article full text in HTML. The icon URL leads to the icon file in jpeg format. The UrlName field is not populated for either article. The subject type was not provided in the identity file, and consequently it must be listed here. The articles are available free. The Attribute field provides information about the article format: Full-text Online (HTML).
Note that each field must be comma separated.
Field 1: PrId. 1234
Field 2: DB. PubMed
Field 3: Query. "Korean J Pathol"[ta] AND 48[vol] AND 466[pg] and "Korean J Pathol"[ta] AND 48[vol] AND 462[pg]
Field 4: URL. https://koreanjpathol.org/archive/view.php?year=2014&vol=48&no=6&startpage=466 and https://koreanjpathol.org/archive/view.php?year=2014&vol=48&no=6&startpage=462
Filed 5: IconUrl. https://www.koreanjpathol.org/image/kjpathol_linkout.gif
Field 6: UrlName None
Field 7: SubjectType. Publishers/providers
Field 8: Attribute. Full-text Online
A sample file using a spreadsheet program such as MS Excel.
| PrId | DB | Query | URL | IconUrl | UrlName | SubjectType | Attribute |
|---|---|---|---|---|---|---|---|
| 1234 | PubMed | "Korean J Pathol"[ta] AND 48[vol] AND 466[pg] | https://koreanjpathol.org/archive/view.php?year=2014&vol=48&no=6&startpage=466 |
https://www.koreanjpathol.org/image/kjpathol_linkout.gif | publishers/providers | Full-text Online | |
| 1234 | PubMed | "Korean J Pathol"[ta] AND 48[vol] AND 462[pg] | https://koreanjpathol.org/archive/view.php?year=2014&vol=48&no=6&startpage=462 |
https://www.koreanjpathol.org/image/kjpathol_linkout.gif | publishers/providers | Full-text Online |
The same entries in a sample CSV file can be downloaded here. Save files with the extension .csv, and upload them to the “holdings” directory of the FTP assigned to you.
File Evaluation
After your application for inclusion in LinkOut has been accepted, prepare an identity file and a sample resource file. Resource files should contain links to at least five PubMed records.
Validate the files using the LinkOut https://www.ncbi.nlm.nih.gov/projects/linkout/doc/file-validator.html. Email the files to vog.hin.mln.ibcn@tuoknil.
Your files will be evaluated by the LinkOut team, and you will be contacted regarding any corrections. The evaluation process will continue until your files are substantially error free.
Account Assignment
When the submitted files are substantially error free, you will be assigned a ProviderId (PrId) and an approved name abbreviation (NameAbbr), and you will be given a password for an NCBI private FTP account.
Please note that each provider will be given only one FTP account at NCBI. A single provider may submit links on behalf of multiple publishers; different icons may be used in PubMed to establish the identity for each journal.
File Transfer
When you receive your account information, validate the files using the LinkOut https://www.ncbi.nlm.nih.gov/projects/linkout/doc/file-validator.html and transfer all files via FTP. Place the files in the “holdings” directory of your account. No subdirectories may be created in the holdings subdirectory.
When files have been submitted, inform the LinkOut team at vog.hin.mln.ibcn@tuoknil. Your files will be given a final evaluation before being placed in the production queue. From this point on, files will be processed automatically every day.
Links should appear in PubMed within 2 days of file submission. If 2 days have passed and you do not see your links in PubMed, please write to vog.hin.mln.ibcn@tuoknil.
File Maintenance
Provider Responsibilities
Link providers are responsible for:
• maintaining their LinkOut files
• transferring any additions, changes, or deletions of their links to NCBI
• updating files and informing NCBI when access rights are changed
• correcting broken or incorrect links in a timely manner
Providers may transfer new versions of current files or add new resource files at any time. It is the responsibility of the provider to keep files current and valid. Links in PubMed are regenerated every day based on the resource files in each provider’s directory; therefore, providers must delete obsolete files from their /holdings directory.
Additional provider responsibilities are described in LinkOut Policies: Provider Responsibilities.
Confirmation and Error Messages
Upon processing an updated file, NCBI will send an acknowledgement to the designated LinkOut contact. If you prefer not to receive this acknowledgement, please notify the LinkOut Team at [email protected].
If files cannot be processed because of errors, a message with the subject line “LinkOut files uploaded to NCBI - Critical ERRORS!” will be sent to the LinkOut contact. The files should be corrected and resubmitted. If you have any questions about the errors, contact LinkOut at vog.hin.mln.ibcn@tuoknil.
Provider Statistics
LinkOut collects statistics on the number of clicks on each publisher’s icons in PubMed’s Abstract display and clicks on the publisher’s links in the LinkOut list of resources.
Statistics can be emailed to the LinkOut contact monthly. If you would like to receive statistics, please notify the LinkOut Team at vog.hin.mln.ibcn@tuoknil
Statistics send via email include the yearly and monthly totals for clicks on a provider’s links, which are sorted by journal (a CSV file with the same information is provided as an attachment as well).
Statistics may change for the first 2 weeks that they are available. After 2 weeks, statistics will be stable.
A sample statistics report is shown below:
Additional Information about Linking
Section Contents
Deleted PMIDs
From time to time, records are deleted from the PubMed database. If you provide links using PMIDs in LinkOut files and the PMIDs are deleted, your links will disappear from PubMed. If you use these PMIDs to link to PubMed from your system, these links will be broken.
A list of all deleted PMIDs is available here:
https://ftp.ncbi.nlm.nih.gov/pubmed/deleted.pmids.gz
Please consult this list frequently to synchronize your linking system with PubMed to ensure proper functioning of your links.
Adding/Changing DOI/PII in PubMed Records (for Linking Purposes Only)
NLM and NCBI do not input DOI or PII in PubMed records; this information must be submitted by providers that are submitting journal citation data. For citations that are already in PubMed, DOI/PII information can be added or updated in the ArticleID IdType element of the citation XML by providing the new or updated information to NCBI. Only the current citation data provider of a journal title would be able to submit DOI/PII information.
To submit updated DOI/PII for PubMed records, upload a simple text file containing PMID and DOI/PII pairs in two columns:
- Locate the PubMed citation IDs (PMID) of the citations for which DOI/PII will be added or updated.
- Create a text file of PMID</tab>DOI or PMID</tab>PII pairs (</tab> refers to the tab key). For example:
12345678 10.1234/2013/999990.
- Each pair should appear on one line.
- DOI files must have the extension .doi.
- PII files must have the extension .pii.
- Each file may contain up to 10,000 pairs. You may submit multiple files.
Place DOI or PII files in the pid directory of the FTP assigned to you. If you don’t have a pid directory in your assigned FTP, write to vog.hin.mln.ibcn@tuoknil to request a pid directory.
Transferring Journals Between Publishers
When a journal is transferred to a new publisher, LinkOut needs to be informed so that the default icon can be changed, and to ensure that links continue to function properly. To do this, please send the following information to .vog.hin.mln.ibcn@tuoknil
- Is the journal being added or deleted?
- Journal title and ISSN.
- Publisher name and LinkOut account name.
If the journal is being added to your collection, please also include the following:
- Name of previous publisher
- When will change take place?
- When will you start submitting citation data?
- When will you submit links for the journal? (This should be done after citation files are submitted for the first time.)
- Will back content of the journal be hosted on your site?
- Will libraries that subscribe to the journal have access to all content available for the journal at your site?
- Should your icons appear on back content in PubMed? (This can be done only if the previous publisher’s links are not working, or if the copyright holder approves the change.)
If the journal is being removed from your collection, please also include the following:
- Is the journal being transferred to a new publisher? Which?
- When will the change take place?
- When will you stop submitting links for the journal or update your LinkOut files to stop links from being generated for new content?
- Will back content continue to be hosted at your site?
- Should your icons appear on back content in PubMed? (If links are not working, they will be removed. Icon can continue to appear on back content if copyright holder approves it.)
Both old and new provider links should be working during the transition
- Information for Full-Text Providers - LinkOut HelpInformation for Full-Text Providers - LinkOut Help
Your browsing activity is empty.
Activity recording is turned off.
See more...