deps.dev API
Overview
The deps.dev API provides access to Open Source Insights data. It can be used by tool builders, researchers, and tinkerers who want to answer questions like:
- What versions are available for this package?
- What are the licenses that cover this version of a package?
- How many dependencies does this package have? What are they?
- What versions of what packages correspond to this file?
The API can be accessed in two ways: as JSON over HTTP, which is described on this page, as well as via gRPC. For more information about accessing the API via gRPC, please visit github.com/google/deps.dev.
Using the API
You can access the API using any HTTP client. To quickly get started, you can
use the curl
command-line tool.
The methods of the API accept parameters. Required parameters are passed as part of the request path, while optional parameters are passed as part of the query string.
All parameters must be encoded so that they can be safely included in a URL,
by replacing special characters (e.g. /
) with their percent-encoded forms
(e.g. %2F
). This can be done using functions such as
encodeURIComponent
in JavaScript, url.PathEscape and
url.QueryEscape in Go, or the
equivalent in your programming language of choice.
For example, to get information about the npm package @colors/colors
:
curl 'https://api.deps.dev/v3alpha/systems/npm/packages/%40colors%2Fcolors'
Note that the @
and /
in the package name have been percent-encoded.
Parameters representing data blobs, such as hash values, are passed as base64 strings.
For example, to use the Query API method to look up package versions by file content hash:
curl -G \
--data-urlencode 'hash.type=SHA1' \
--data-urlencode 'hash.value=ulXBPXrC/UTfnMgHRFVxmjPzdbk=' \
'https://api.deps.dev/v3alpha/query'
Note that we use the --data-urlencode
flag as a convenient way to construct a
query string with percent-encoded values.
To compute a base64-encoded hash from a file’s contents suitable for use as a
hash.value
query parameter you can use the openssl
and base64
commands:
openssl sha1 -binary <file> | base64
Package names
In general, the API refers to packages by the names used within their ecosystem, including details such as capitalization.
Exceptions:
- Maven names are of the form
<group ID>:<artifact ID>
, for exampleorg.apache.logging.log4j:log4j-core
. - PyPI names are normalized as per PEP 503.
- NuGet names are normalized through lowercasing according to the Package Content API request parameter specification. Versions are normalized according to NuGet 3.4+ rules.
Coverage
In general, the service collects all publicly-available data from each source (for example, it gathers all npm packages hosted by registry.npmjs.org).
Exceptions:
- For Maven packages, in addition to Maven Central, it gathers artifacts from the Jenkins and Google registries.
- For PyPI it only collects packages released as wheels and sdists.
- For Go it only collects modules that have been fetched through proxy.golang.org, and those declared as dependencies by those modules.
- For projects hosted on GitHub, GitLab, and Bitbucket it only gathers projects associated with a package otherwise known to the service.
API reference
GetPackage
GET /v3alpha/systems/{packageKey.system}/packages/{packageKey.name}
GetPackage returns information about a package, including a list of its available versions, with the default version marked if known.
Example: /v3alpha/systems/npm/packages/%40colors%2Fcolors
Path parameters
- packageKey.system: string
The package management system containing the package.
Can be one of
GO
,NPM
,CARGO
,MAVEN
,PYPI
,NUGET
- packageKey.name: string
The name of the package.
Response
- packageKey: object
The name of the package. Note that it may differ from the name in the request, due to canonicalization.
- packageKey.system: string
The package management system containing the package.
Can be one of
GO
,NPM
,CARGO
,MAVEN
,PYPI
,NUGET
- packageKey.name: string
The name of the package.
- versions[]: object[]
The available versions of the package.
- versions[].versionKey: object
The name of the version. Note that the package name may differ from the name in the request, due to canonicalization.
- versions[].versionKey.system: string
The package management system containing the package.
Can be one of
GO
,NPM
,CARGO
,MAVEN
,PYPI
,NUGET
- versions[].versionKey.name: string
The name of the package.
- versions[].versionKey.version: string
The version of the package.
- versions[].isDefault: boolean
If true, this is the default version of the package: the version that is installed when no version is specified. The precise meaning of this is system-specific, but it is commonly the version with the greatest version number, ignoring pre-release versions.
GetVersion
GET /v3alpha/systems/{versionKey.system}/packages/{versionKey.name}/versions/{versionKey.version}
GetVersion returns information about a specific package version, including its licenses and any security advisories known to affect it.
Example: /v3alpha/systems/npm/packages/%40colors%2Fcolors/versions/1.5.0
Path parameters
- versionKey.system: string
The package management system containing the package.
Can be one of
GO
,NPM
,CARGO
,MAVEN
,PYPI
,NUGET
- versionKey.name: string
The name of the package.
- versionKey.version: string
The version of the package.
Response
- versionKey: object
The name of the package version. Note that the package and version name may differ from names specified in requests, if applicable, due to canonicalization.
- versionKey.system: string
The package management system containing the package.
Can be one of
GO
,NPM
,CARGO
,MAVEN
,PYPI
,NUGET
- versionKey.name: string
The name of the package.
- versionKey.version: string
The version of the package.
- isDefault: boolean
If true, this is the default version of the package: the version that is installed when no version is specified. The precise meaning of this is system-specific, but it is commonly the version with the greatest version number, ignoring pre-release versions.
- licenses[]: string[]
The licenses governing the use of this package version.
We identify licenses as SPDX 2.1 expressions. When there is no associated SPDX identifier, we identify a license as “non-standard”. When we are unable to obtain license information, this field is empty. When more than one license is listed, their relationship is unspecified.
For Cargo, Maven, npm, and PyPI, license information is read from the package metadata. For Go, license information is determined using the licensecheck package.
License information is not intended to be legal advice, and you should independently verify the license or terms of any software for your own needs.
- advisoryKeys[]: object[]
Security advisories known to affect this package version. Further information can be requested using the Advisory method.
- advisoryKeys[].id: string
The OSV identifier for the security advisory.
- links[]: object[]
Links declared by or derived from package version metadata, to external web resources such as a homepage or source code repository. Note that these links are not verified for correctness.
- links[].label: string
A label describing the resource that the link points to.
- links[].url: string
The URL of the link.
GetRequirements
GET /v3alpha/systems/{versionKey.system}/packages/{versionKey.name}/versions/{versionKey.version}:requirements
GetRequirements returns the requirements for a given version in a system-specific format. Requirements are currently only available for NuGet.
Requirements are the dependency constraints specified by the version.
Example: /v3alpha/systems/nuget/packages/castle.core/versions/5.1.1:requirements
Path parameters
- versionKey.system: string
The package management system containing the package.
Can be one of
GO
,NPM
,CARGO
,MAVEN
,PYPI
,NUGET
- versionKey.name: string
The name of the package.
- versionKey.version: string
The version of the package.
Response
- nuget: object
The NuGet-specific representation of the version’s requirements.
Note that the term “dependency” is used here to mean “a single unresolved requirement” to be consistent with how the term is used in the NuGet ecosystem. This is different to how it is used elsewhere in the deps.dev API.
- nuget.dependencyGroups[]: object[]
The requirements grouped by target framework.
- nuget.dependencyGroups[].targetFramework: string
The target framework that this dependency group is for.
- nuget.dependencyGroups[].dependencies[]: object[]
The requirements belonging to this dependency group.
- nuget.dependencyGroups[].dependencies[].name: string
The name of the package.
- nuget.dependencyGroups[].dependencies[].requirement: string
The requirement on the package.
GetDependencies
GET /v3alpha/systems/{versionKey.system}/packages/{versionKey.name}/versions/{versionKey.version}:dependencies
GetDependencies returns a resolved dependency graph for the given package version. Dependencies are currently available for Go, npm, Cargo, Maven and PyPI.
Dependencies are the resolution of the requirements (dependency constraints) specified by a version.
The dependency graph should be similar to one produced by installing the package version on a generic 64-bit Linux system, with no other dependencies present. The precise meaning of this varies from system to system.
Example: /v3alpha/systems/npm/packages/react/versions/18.2.0:dependencies
Path parameters
- versionKey.system: string
The package management system containing the package.
Can be one of
GO
,NPM
,CARGO
,MAVEN
,PYPI
,NUGET
- versionKey.name: string
The name of the package.
- versionKey.version: string
The version of the package.
Response
- nodes[]: object[]
The nodes of the dependency graph. The first node is the root of the graph.
- nodes[].versionKey: object
The package version represented by this node. Note that the package and version name may differ from the names in the request, if provided, due to canonicalization.
For some systems, a graph may contain multiple nodes for the same package version.
- nodes[].versionKey.system: string
The package management system containing the package.
Can be one of
GO
,NPM
,CARGO
,MAVEN
,PYPI
,NUGET
- nodes[].versionKey.name: string
The name of the package.
- nodes[].versionKey.version: string
The version of the package.
- nodes[].bundled: boolean
If true, this is a bundled dependency. For bundled dependencies, the package name in the version key encodes how the dependency is bundled.
As an example, a bundled dependency with a name like “a>1.2.3>b>c” is part of the dependency graph of package “a” at version “1.2.3”, and has the local name “c”. It may or may not be the same as a package with the global name “c”.
- nodes[].relation: string
Whether this node represents a direct or indirect dependency within this dependency graph. Note that it’s possible for a dependency to be both direct and indirect; if so, it is marked as direct.
Can be one of
SELF
,DIRECT
,INDIRECT
- nodes[].errors[]: string[]
Errors associated with this node of the graph, such as an unresolved dependency requirement. An error on a node may imply the graph as a whole is incorrect. These error messages have no defined format and are intended for human consumption.
- edges[]: object[]
The edges of the dependency graph.
- edges[].fromNode: number
The node declaring the dependency, specified as an index into the list of nodes.
- edges[].toNode: number
The node resolving the dependency, specified as an index into the list of nodes.
- edges[].requirement: string
The requirement resolved by this edge, as declared by the “from” node. The meaning of this field is system-specific. As an example, in npm, the requirement “^1.0.0” may be resolved by the version “1.2.3”.
- error: string
Any error associated with the dependency graph that is not specific to a node. An error here may imply the graph as a whole is incorrect. This error message has no defined format and is intended for human consumption.
GetProject
GET /v3alpha/projects/{projectKey.id}
GetProject returns information about projects hosted by GitHub, GitLab, or BitBucket, when known to us.
Example: /v3alpha/projects/github.com%2Ffacebook%2Freact
Path parameters
- projectKey.id: string
A project identifier of the form
github.com/user/repo
,gitlab.com/user/repo
, orbitbucket.org/user/repo
.
Response
- projectKey: object
The identifier for the project. Note that this may differ from the identifier in the request, due to canonicalization.
- projectKey.id: string
A project identifier of the form
github.com/user/repo
,gitlab.com/user/repo
, orbitbucket.org/user/repo
.- openIssuesCount: number
The number of stars reported by the project host. Only available for GitHub and GitLab.
- starsCount: number
The number of stars reported by the project host. Only available for GitHub and GitLab.
- forksCount: number
The number of forks reported by the project host. Only available for GitHub and GitLab.
- license: string
The license reported by the project host.
- description: string
The description reported by the project host.
- homepage: string
The homepage reported by the project host.
- scorecard: object
An OpenSSF Scorecard for the project, if one is available.
- scorecard.date: string
The date at which the scorecard was produced.
- scorecard.repository: object
The source code repository and commit the scorecard was produced from.
- scorecard.repository.name: string
The source code repository the scorecard was produced from.
- scorecard.repository.commit: string
The source code commit the scorecard was produced from.
- scorecard.scorecard: object
The version and commit of the Scorecard program used to produce the scorecard.
- scorecard.scorecard.version: string
The version of the Scorecard program used to produce the scorecard.
- scorecard.scorecard.commit: string
The commit of the Scorecard program used to produce the scorecard.
- scorecard.checks[]: object[]
The results of the Scorecard Checks performed on the project.
- scorecard.checks[].name: string
The name of the check.
- scorecard.checks[].documentation: object
Human-readable documentation for the check.
- scorecard.checks[].documentation.shortDescription: string
A short description of the check.
- scorecard.checks[].documentation.url: string
A link to more details about the check.
- scorecard.checks[].score: number
A score in the range [0,10]. A higher score is better. A negative score indicates that the check did not run successfully.
- scorecard.checks[].reason: string
The reason for the score.
- scorecard.checks[].details[]: string[]
Further details regarding the check.
- scorecard.overallScore: number
A weighted average score in the range [0,10]. A higher score is better.
- scorecard.metadata[]: string[]
Additional metadata associated with the scorecard.
GetAdvisory
GET /v3alpha/advisories/{advisoryKey.id}
GetAdvisory returns information about security advisories hosted by OSV.
Example: /v3alpha/advisories/GHSA-2qrg-x229-3v8q
Path parameters
- advisoryKey.id: string
The OSV identifier for the security advisory.
Response
- advisoryKey: object
The identifier for the security advisory. Note that this may differ from the identifier in the request, due to canonicalization.
- advisoryKey.id: string
The OSV identifier for the security advisory.
- url: string
The URL of the security advisory.
- title: string
A brief human-readable description.
- aliases[]: string[]
Other identifiers used for the advisory, including CVEs.
- cvss3Score: number
The severity of the advisory as a CVSS v3 score in the range [0,10]. A higher score represents greater severity.
- cvss3Vector: string
The severity of the advisory as a CVSS v3 vector string.
Query
GET /v3alpha/query
Query returns information about multiple package versions, which can be specified by name, content hash, or both.
It is typical for hash queries to return many results; hashes are matched against multiple artifacts that comprise package versions, and any given artifact may appear in many package versions.
Examples:
/v3alpha/query?hash.type=SHA1&hash.value=ulXBPXrC%2fUTfnMgHRFVxmjPzdbk%3d
/v3alpha/query?versionKey.system=NPM&versionKey.name=react&versionKey.version=18.2.0
Query parameters
- hash.type: string
The function used to produce this hash.
Can be one of
MD5
,SHA1
,SHA256
,SHA512
- hash.value: string
A hash value.
- versionKey.system: string
The package management system containing the package.
Can be one of
GO
,NPM
,CARGO
,MAVEN
,PYPI
,NUGET
- versionKey.name: string
The name of the package.
- versionKey.version: string
The version of the package.
Response
- versions[]: object[]
Package versions matching the query. At most 1000 versions are returned.
- versions[].versionKey: object
The name of the package version. Note that the package and version name may differ from names specified in requests, if applicable, due to canonicalization.
- versions[].versionKey.system: string
The package management system containing the package.
Can be one of
GO
,NPM
,CARGO
,MAVEN
,PYPI
,NUGET
- versions[].versionKey.name: string
The name of the package.
- versions[].versionKey.version: string
The version of the package.
- versions[].isDefault: boolean
If true, this is the default version of the package: the version that is installed when no version is specified. The precise meaning of this is system-specific, but it is commonly the version with the greatest version number, ignoring pre-release versions.
- versions[].licenses[]: string[]
The licenses governing the use of this package version.
We identify licenses as SPDX 2.1 expressions. When there is no associated SPDX identifier, we identify a license as “non-standard”. When we are unable to obtain license information, this field is empty. When more than one license is listed, their relationship is unspecified.
For Cargo, Maven, npm, and PyPI, license information is read from the package metadata. For Go, license information is determined using the licensecheck package.
License information is not intended to be legal advice, and you should independently verify the license or terms of any software for your own needs.
- versions[].advisoryKeys[]: object[]
Security advisories known to affect this package version. Further information can be requested using the Advisory method.
- versions[].advisoryKeys[].id: string
The OSV identifier for the security advisory.
- versions[].links[]: object[]
Links declared by or derived from package version metadata, to external web resources such as a homepage or source code repository. Note that these links are not verified for correctness.
- versions[].links[].label: string
A label describing the resource that the link points to.
- versions[].links[].url: string
The URL of the link.
Contact us
If you have questions about the API, or want to report a problem, please create an issue or contact us at open-source-insights@google.com.
Terms
Use of the deps.dev API is subject to the Google API Terms of Service.