API reference

kegg_info(database::String) -> String

Get information about a specific database from the KEGG API.

Allowed database values are:

kegg     | pathway | brite   | module  | ko      | genes    | <org>   |
ag       | vg      | vp      | genome  | vtax    | vgenome  | ligand  |
compound | glycan  | reaction| rclass  | rmodule | enzyme   | network |
ntmap    | variant | disease | drug    | dgroup

Arguments

• database::String: The KEGG database for which to retrieve information.

Returns

• String: Database release information and statistics from KEGG.

Example

julia> info = kegg_info("kegg");

julia> occursin("KEGG", info)
true

Extended help

kegg_info returns database release information and statistics. For databases other than kegg, genes, and ligand, the response also lists databases that can be passed to kegg_link.

Reference

• https://www.kegg.jp/kegg/rest/keggapi.html#info

kegg_list(query::String, query_type::String = "") -> Union{KeggTupleList, KeggGenesList}

Get a list of entry identifiers and associated names.

Arguments

• query::String: The KEGG database to list.
• query_type::String: An optional organism code, BRITE prefix, organism group, or taxonomy rank identifier used to narrow the list.

Allowed database values are:

pathway  | brite   | module   | ko      | <org>    | ag     | vg      |
vp       | genome  | vtax     | vgenome | compound | glycan | reaction|
rclass   | rmodule | enzyme   | network | ntmap    | variant| disease |
drug     | dgroup

Returns

• KeggTupleList: A two-column response, a response with an unrecognized width, or an empty response, together with its request URL and column names.
• KeggGenesList: The four columns in an organism-specific gene response, together with its request URL and column names.

Examples

julia> result = kegg_list("pathway", "hsa");

julia> result isa KEGGAPI.KeggTupleList && !isempty(result.data)
true

Extended help

kegg_list returns entries from the requested database. It accepts the database names above except the composite databases genes and kegg. Use genome to list organisms and their three- or four-letter codes.

The optional query_type becomes the second URL segment. For pathway queries, pass an organism code to list organism-specific pathways. For BRITE queries, pass "br", "jp", "ko", or an organism code. For genome queries, pass an organism group name or taxonomy <rank_id> such as a phylum, class, order, family, genus, or species identifier.

References

• https://www.kegg.jp/kegg/rest/keggapi.html#list

kegg_list(dbentries::Vector{String}; request_delay::Real = 0.4, timeout = nothing) -> KeggTupleList

Get a list of entry identifiers and associated names.

Arguments

• dbentries::Vector{String}: The list of entries to list.
• request_delay::Real: Seconds to wait between batched requests. Defaults to 0.4. No delay occurs when the input fits in one request.
• timeout::Real: Deprecated alias for request_delay. If both keywords are supplied, their values must be equal.

Throws

• ArgumentError: If a delay is negative or non-finite, or if request_delay and timeout conflict.

Returns

• KeggTupleList: The requested entries, request URLs, and column names.

Examples

julia> result = kegg_list(["hsa:10458", "hsa:10459"]);

julia> result isa KEGGAPI.KeggTupleList && result.url isa Vector{String} && length(result.data) == 2
true

Extended help

The input is limited to 10 entries per request. Larger inputs are split into batches, with request_delay seconds between requests and no wait after the final request. The default of 0.4 seconds keeps batched calls below KEGG's limit of three requests per second.

kegg_find(database::String, query::String, option::String = "") -> KeggTupleList

Find entries with a matching query keyword or other query data.

Allowed database values are:

kegg    | pathway | brite    | module | ko       | genes  | <org>  |
ag      | vg      | vp       | genome | vtax     | vgenome| compound|
glycan  | reaction| rclass   | rmodule| enzyme   | network| ntmap  |
variant | disease | drug     | dgroup

Allowed option values (only for the compound and drug databases):

formula | exact_mass | mol_weight | nop

Arguments

• database::String: The KEGG database to search.
• query::String: The query keyword or data. Spaces are converted to +.
• option::String: For the compound/drug databases, restrict the search to a chemical field. nop disables keyword pre-processing.

Returns

• KeggTupleList: The matching identifiers and descriptions, with the request URL and column names.

Examples

julia> result = kegg_find("compound", "glucose");

julia> result isa KEGGAPI.KeggTupleList && result.colnames == ["ID", "Details"] && !isempty(result.data)
true

Extended help

kegg_find searches a KEGG database for entries that match query. For compound and drug, use option to search by formula, exact_mass, or mol_weight. Specify a range with a hyphen, as in "300-310". The nop option disables keyword preprocessing. The function accepts recognized KEGG databases and organism codes. It warns about other database names before passing them to the API.

Reference

• https://www.kegg.jp/kegg/rest/keggapi.html#find

kegg_get(dbentries::Vector{String}, option::Union{Symbol, Nothing} = nothing; request_delay::Real = 0.4, timeout = nothing) -> NamedTuple
kegg_get(dbentry::String, option::Union{Symbol, Nothing} = nothing; request_delay::Real = 0.4, timeout = nothing) -> NamedTuple

Retrieve given database entries.

Allowed dbentries (database entries):

pathway   | brite    | module   | ko       | <org>    | ag         | vg      |
vp        | genome   | vtax     | vgenome  | compound | glycan     | reaction|
rclass    | rmodule  | enzyme   | network  | ntmap    | variant    | disease |
drug      | dgroup   | disease_ja| drug_ja | dgroup_ja| compound_ja

Allowed option for retrieval of selected fields:

:aaseq | :ntseq | :mol | :kcf | :image | :image2x | :conf | :kgml | :json | nothing

Arguments

• dbentries::Vector{String}: A vector of KEGG database entries to retrieve.
• option::Union{Symbol, Nothing}: An optional symbol specifying the format of the retrieved data. If nothing, the default format is used.
• request_delay::Real: Seconds to wait between batched requests. Defaults to 0.4. No delay occurs when the input fits in one request.
• timeout::Real: Deprecated alias for request_delay. If both keywords are supplied, their values must be equal.

Throws

• ArgumentError: If a delay is negative or non-finite, or if request_delay and timeout conflict.

Returns

• For vector input, a named tuple (url = urls, data = data). urls is a Vector{String} containing one URL per request batch. data is a vector with one processed result per retrieved entry.
• For scalar input, a named tuple (url = url, data = data). url is the single request URL. data is a String for text and sequence formats and a Vector{UInt8} for :image and :image2x.

Examples

julia> result = kegg_get(["hsa:10458", "hsa:10459"], :aaseq);

julia> (result.url isa Vector{String}, length(result.data), all(item -> item isa String, result.data))
(true, 2, true)

julia> result = kegg_get("hsa:10458");

julia> (result.url isa String, result.data isa String)
(true, true)

Extended help

kegg_get retrieves entries as KEGG flat files or in the format selected by option. Flat files are supported for every KEGG database except brite. Each request accepts at most 10 entries, so the function splits longer inputs into batches. It waits request_delay seconds between batches but not after the final request. The default of 0.4 seconds keeps batched calls below KEGG's limit of three requests per second.

Use option to retrieve gene sequences, chemical structures, compound, glycan, or drug images, pathway images, or KGML files. The :image2x option retrieves a reference pathway map at double size.

The input is limited to one compound/glycan/drug entry with the :image option, and to one pathway entry with the :image, :image2x or :kgml option.

Reference

• https://www.kegg.jp/kegg/rest/keggapi.html#get

kegg_conv(target_db::String, source_db::String) -> KeggTupleList

Convert KEGG identifiers to/from outside identifiers.

Arguments

• target_db::String: Target database
• source_db::String: Source database

Returns

• KeggTupleList: The requested identifier mappings, with the request URL and column names.

Examples

julia> result = kegg_conv("genes", "ncbi-geneid:948364");

julia> result isa KEGGAPI.KeggTupleList && !isempty(result.data)
true

Extended help

Convert outside accession numbers to KEGG identifiers or KEGG identifiers to outside accession numbers. Pass database names for database-to-database mapping, or pass one or more entries to convert selected identifiers. The genes database is valid only when converting selected entries.

References

• KEGG API

kegg_conv(target_db::String, dbentries::Vector{String}; request_delay::Real = 0.4, timeout = nothing) -> KeggTupleList

Convert KEGG identifiers to/from outside identifiers.

For gene identifiers:

<dbentries> = database entries of the following <database>
<database>  = <org> | genes | ncbi-geneid | ncbi-proteinid | uniprot
<org>       = KEGG organism code or T number

For chemical substance identifiers:

<dbentries> = database entries of the following <database>
<database>  = compound | glycan | drug | pubchem | chebi

Arguments

• target_db::String: Target database
• dbentries::Vector{String}: Entries to convert.
• request_delay::Real: Seconds to wait between batched requests. Defaults to 0.4. No delay occurs when the input fits in one request.
• timeout::Real: Deprecated alias for request_delay. If both keywords are supplied, their values must be equal.

Returns

• KeggTupleList: The requested identifier mappings, request URLs, and column names.

Throws

• ArgumentError: If a delay is negative or non-finite, or if request_delay and timeout conflict.

Examples

julia> result = kegg_conv("ncbi-proteinid", ["hsa:10458", "ece:Z5100"]);

julia> result isa KEGGAPI.KeggTupleList && result.url isa Vector{String} && !isempty(result.data)
true

kegg_link(target_db::String, source_db::String, option::String = "") -> Union{KeggTupleList, String}

Find related entries by using database cross-references.

The available KEGG databases are:

pathway | brite    | module | ko      | <org>   | ag     | vg      |
vp      | genome   | vtax   | vgenome | compound| glycan | reaction|
rclass  | rmodule  | enzyme | network | ntmap   | variant | disease |
drug    | dgroup   | <outside_db>

and the available external databases are:

pubmed | taxonomy | atc | jtc | ndc | yk

Arguments

• target_db::String: Target database
• source_db::String: Source database
• option::String: Optional refinement of the query. For genome/taxonomy links a taxonomic rank may be given (species | genus | family | order | class | phylum). For the drug/atc/jtc databases an RDF output format may be requested (turtle | n-triple), in which case the raw response text is returned instead of a KeggTupleList.

Returns

• KeggTupleList: The linked identifiers, request URL, and column names for tabular responses.
• String: The raw RDF response when option is "turtle" or "n-triple".

Examples

julia> links = kegg_link("pathway", "hsa:10458");

julia> links isa KEGGAPI.KeggTupleList && !isempty(links.data)
true

julia> rdf = kegg_link("atc", "D00564", "turtle");

julia> rdf isa String && !isempty(rdf)
true

Extended help

kegg_link retrieves cross-references within KEGG and between KEGG and outside databases. Pass database names to retrieve all links between two databases, or pass entry identifiers to retrieve links for selected entries.

kegg_link(target_db::String, dbentries::Vector{String}, option::String = ""; request_delay::Real = 0.4, timeout = nothing) -> Union{KeggTupleList, String}

Find related entries by using database cross-references.

The available KEGG databases are:

pathway | brite    | module | ko      | <org>   | ag     | vg      |
vp      | genome   | vtax   | vgenome | compound| glycan | reaction|
rclass  | rmodule  | enzyme | network | ntmap   | variant | disease |
drug    | dgroup   | <outside_db>

and the available external databases are:

pubmed | taxonomy | atc | jtc | ndc | yk

Arguments

• target_db::String, target database
• dbentries::Vector{String}, entries from the source database
• option::String, optional refinement of the query. A taxonomic rank (species | genus | family | order | class | phylum) for genome/taxonomy links, or an RDF output format (turtle | n-triple) for the drug/atc/jtc databases (in which case the raw response text is returned).
• request_delay::Real, seconds to wait between batched requests. Defaults to 0.4. No delay occurs when the input fits in one request.
• timeout::Real, deprecated alias for request_delay. If both keywords are supplied, their values must be equal.

Returns

• KeggTupleList: The linked identifiers, request URLs, and column names for tabular responses.
• String: The concatenated raw RDF responses when option is "turtle" or "n-triple".

Throws

• ArgumentError: If a delay is negative or non-finite, or if request_delay and timeout conflict.

Examples

julia> links = kegg_link("pathway", ["hsa:10458", "hsa:10459"]);

julia> links isa KEGGAPI.KeggTupleList && links.url isa Vector{String} && !isempty(links.data)
true

The vector form sends at most 10 entries per request. It waits request_delay seconds between requests, but does not wait after the final request.

kegg_ddi(dbentry::String) -> KeggTupleList
kegg_ddi(dbentries::Vector{String}) -> KeggTupleList

Find adverse drug-drug interactions (DDI).

The available databases are:

drug | ndc | yj

Arguments

• dbentry::String / dbentries::Vector{String}: KEGG DRUG (dr:/D numbers), NDC or YJ code entries to query for interactions.

Returns

• KeggTupleList: The interactions, request URL or URLs, and column names. The columns are ["Entry 1", "Entry 2", "Interaction Type", "Mechanism"], where the interaction type is CI (contraindication) or P (precaution).

Throws

• ArgumentError: If dbentries is empty

Examples

julia> result = kegg_ddi(["D00564", "D00100"]);

julia> result isa KEGGAPI.KeggTupleList && result.colnames == ["Entry 1", "Entry 2", "Interaction Type", "Mechanism"]
true

Extended help

The KEGG DDI database records known adverse drug-drug interactions. A query with multiple entries also returns pairwise interactions among those entries. Vector inputs must contain between one and ten entries. Empty vectors and vectors with more than ten entries throw an ArgumentError before a request is sent. Queries above the KEGG limit cannot be split into independent requests because doing so would omit interactions between entries in different requests.

Reference

• https://www.kegg.jp/kegg/rest/keggapi.html#ddi

@kegg_str -> NamedTuple

Retrieve a KEGG flat-file entry with string-macro syntax in the REPL.

See kegg_get for accepted database entries.

Returns

• NamedTuple: The same (url = url, data = data) result as scalar kegg_get.

Example

julia> entry = kegg"hsa:10458";

julia> (entry.url isa String, entry.data isa String)
(true, true)

request(url::String [, T::Type = String]) -> T

Send a GET request to a KEGG API URL. This low-level function is an escape hatch for valid KEGG endpoints that do not have a dedicated KEGGAPI.jl wrapper.

The default T is String. Pass Vector{UInt8} to return the response body as raw bytes, for example when requesting an image. Other response types must be constructible from a Vector{UInt8}.

HTTP.jl exceptions pass through unchanged. Connection failures, including DNS and TLS failures, throw HTTP.Exceptions.ConnectError. Failures while sending a request or reading its response throw HTTP.Exceptions.RequestError, timeouts throw HTTP.Exceptions.TimeoutError, and unsuccessful HTTP responses throw HTTP.Exceptions.StatusError. The HTTP exceptions retain the underlying error or response in their fields.

Examples

request is not exported, so call it with the KEGGAPI module prefix.

julia> text = KEGGAPI.request("https://rest.kegg.jp/info/kegg");

julia> occursin("KEGG", text)
true

julia> image = KEGGAPI.request("https://rest.kegg.jp/get/hsa00010/image", Vector{UInt8});

julia> image[1:8] == UInt8[0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
true

Arguments

• url::String: A KEGG API URL.
• T::Type: The response body type. Defaults to String.

Returns

• T: The response body converted to the requested type.

Throws

• HTTP.Exceptions.ConnectError: If HTTP.jl cannot establish a connection.
• HTTP.Exceptions.RequestError: If HTTP.jl cannot send the request or read the response.
• HTTP.Exceptions.TimeoutError: If the request exceeds HTTP.jl's read timeout.
• HTTP.Exceptions.StatusError: If the server returns an unsuccessful status.