optimade
Version:
Aggregating Optimade client for the online materials databases
97 lines (70 loc) • 3.1 kB
Markdown
# Aggregating Optimade client for the online materials databases
[](https://www.npmjs.com/package/optimade)
[](https://www.npmjs.com/package/optimade)
[](https://github.com/tilde-lab/optimade-client/issues)
## Features
- discovers all the [official Optimade databases](https://providers.optimade.org) recursively
- caches the discovered list (`prefetched.json`) for future and boosts the retrieval performance
- queries them all, in the browser, at the server, everywhere
- provides pagination, with the minimized number of pages
## Install
```sh
npm i optimade --save
```
```sh
yarn add optimade
```
CDN: [UNPKG](https://unpkg.com/optimade/) |
[jsDelivr](https://cdn.jsdelivr.net/npm/optimade/) (available as
`window.optimade`)
If you are **not** using ES6 or CDN, add to your HTML just before closing the
`body` tag:
```html
<script src="/path/to/optimade/dist/index.js"></script>
<!-- OR -->
<script type="module" src="/path/to/optimade/dist/index.mjs"></script>
```
## Usage
The code is generally isomorphic, however one should additionally take care of
downloading the cache or setting the CORS policy for the browsers. Concerning
the CORS, the `Optimade` class constructor accepts the `corsProxyUrl` parameter,
pointing to a running `cors-anywhere` proxy instance. This will be valid
until all the Optimade providers are supplying the header
`Access-Control-Allow-Origin $http_origin` in their responses. For the
server-side environment this is not required.
### Discovery and querying
```ts
const optimadeClient = new Optimade({
providersUrl: "https://providers.optimade.org/providers.json",
});
console.log(optimadeClient.providers); // { [id: string]: Provider }[]
const providersMap = await optimadeClient.getProviders(); // { [id: string]: Provider }[]
const providerIds = Object.keys(providersMap); // string[]
const results = await optimadeClient.getStructuresAll({
providers: Provider[],
filter: YOUR_OPTIMADE_QUERY,
}); // [StructuresResponse[], Provider][]
```
Importing depends on your environment. See also the `examples` folder. The
`.html` examples are suited for the browser environment, the `.js` examples are
suited for the server environment.
### Pagination
```ts
import prefetched from 'optimade/dist/prefetched.json';
const optimadeClient = new Optimade({
providersUrl: "https://providers.optimade.org/providers.json",
});
optimadeClient.providers = prefetched.providers;
optimadeClient.apis = prefetched.apis;
const results = await optimadeClient.getStructuresAll({
providers: Provider[],
filter: YOUR_OPTIMADE_QUERY,
page: number,
limit: number,
offset: number,
batch: true
}); // [StructuresResponse[], Provider][]
```
See also the `demo` folder.
## License
MIT © [Pavel Malyshev](https://github.com/PaulMaly) and [Alexander Volkov](https://github.com/valexr), Tilde Materials Informatics