| Name | askCO JSON |
| Version |
0.1.6
JSON |
| download |
| home_page | None |
| Summary | Python interface for Te Papa's collections API |
| upload_time | 2024-04-05 01:26:26 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT License |
| keywords |
python
museum
api
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# askCO: search and query records from Te Papa's collections API
This script provides an interface for getting data from the Museum of New Zealand Te Papa Tongarewa. With it, you can run searches and request individual records, which are returned as python objects.
See the [API documentation](https://data.tepapa.govt.nz/docs/) for what's available and how to construct searches.
Te Papa's API requires a registration key in the headers of each request – go to https://data.tepapa.govt.nz/docs/register.html to register. I recommend adding the API key to an environment variable called 'TE-PAPA-KEY', and then calling that from your script to pass to askCO.
## Installation
Install using pip: `pip install askCO`
askCO requires the `requests` module.
## Run a search query
The `tryCO.py` file lays out a prepared search for a page of `Myosotis` specimen records in the `Plants` collection. It calls the API key, sets functional and query parameters, and sets up then runs the search request.
A `Search` request object uses:
- `quiet`: Can be `True` or `False`. If False, askCO prints messages to the console like the URL being requested.
- `timeout`: How long in seconds before the query times out.
- `attempts`: How many times a single query will be retried after an error like a timeout or connection error.
- `endpoint`: Which API endpoint to query. Defaults to `object` but others like `agent`, `taxon`, and `place` are available.
- `query`: The term you're searching for. If not searching for something specific, use the `*` wildcard.
- `filters`: Any filters you want to use in a list of key/value pairs. Can specify a collection to search here.
- `fields`: Cut the response down to specified fields. Leave as `None` to get the full record, or use a list of comma-separated fieldnames.
- `size`: How many results to return at once.
- `start`: Where to begin the page of results. Useful when requesting subsequent pages of a search.
The `Scroll` request object is similar, though it finds and returns all records, not just a page. It uses most of the same parameters, but not `start`. Scrolling works well with a `size` of `1000`. It can also use:
- `duration`: How long to keep the scroll query alive for on the API side. Defaults to `1` minute.
- `max_records`: How many records to retrieve, if you don't want everything.
- `sleep`: How long to wait between requests for scroll pages. Set this to `0.1` to ensure you avoid getting rate limited.
Search and scroll results are stored as a list of dictionaries in the `records` attribute of the request object.
HTTP status is stored as an integer in the `status_code` attribute.
## Get a record
When requesting a single record, the `Resource` request object still uses:
- `api_key`
- `quiet`
- `timeout`
- `attempts`
- `endpoint`
It also takes an `irn` parameter, the specific number for that record within the endpoint. Make sure you've set the correct endpoint - /object/123456 isn't the same as /agent/123456.
The record's data is stored as a dictionary in the `response_text` attribute of the request object.
HTTP status is stored as an integer in the `status_code` attribute.
Get related records by adding the following parameters:
- `related` (set to True)
- `size` (the number of related records to return)
- `types` (a comma separated list of `type` values, eg `Object,Specimen` or `Person`)
Raw data
{
"_id": null,
"home_page": null,
"name": "askCO",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "python, museum, api",
"author": null,
"author_email": "Lucy Schrader <lucy@schrader.nz>",
"download_url": "https://files.pythonhosted.org/packages/56/51/00446932176d18534c727254ead36e63afdf38534215ddc0012da3ab8015/askCO-0.1.6.tar.gz",
"platform": null,
"description": "# askCO: search and query records from Te Papa's collections API\n\nThis script provides an interface for getting data from the Museum of New Zealand Te Papa Tongarewa. With it, you can run searches and request individual records, which are returned as python objects.\n\nSee the [API documentation](https://data.tepapa.govt.nz/docs/) for what's available and how to construct searches.\n\nTe Papa's API requires a registration key in the headers of each request \u2013 go to https://data.tepapa.govt.nz/docs/register.html to register. I recommend adding the API key to an environment variable called 'TE-PAPA-KEY', and then calling that from your script to pass to askCO.\n\n## Installation\nInstall using pip: `pip install askCO`\n\naskCO requires the `requests` module.\n\n## Run a search query\nThe `tryCO.py` file lays out a prepared search for a page of `Myosotis` specimen records in the `Plants` collection. It calls the API key, sets functional and query parameters, and sets up then runs the search request.\n\nA `Search` request object uses:\n- `quiet`: Can be `True` or `False`. If False, askCO prints messages to the console like the URL being requested.\n- `timeout`: How long in seconds before the query times out.\n- `attempts`: How many times a single query will be retried after an error like a timeout or connection error.\n- `endpoint`: Which API endpoint to query. Defaults to `object` but others like `agent`, `taxon`, and `place` are available.\n- `query`: The term you're searching for. If not searching for something specific, use the `*` wildcard.\n- `filters`: Any filters you want to use in a list of key/value pairs. Can specify a collection to search here.\n- `fields`: Cut the response down to specified fields. Leave as `None` to get the full record, or use a list of comma-separated fieldnames.\n- `size`: How many results to return at once.\n- `start`: Where to begin the page of results. Useful when requesting subsequent pages of a search.\n\nThe `Scroll` request object is similar, though it finds and returns all records, not just a page. It uses most of the same parameters, but not `start`. Scrolling works well with a `size` of `1000`. It can also use:\n- `duration`: How long to keep the scroll query alive for on the API side. Defaults to `1` minute.\n- `max_records`: How many records to retrieve, if you don't want everything.\n- `sleep`: How long to wait between requests for scroll pages. Set this to `0.1` to ensure you avoid getting rate limited.\n\nSearch and scroll results are stored as a list of dictionaries in the `records` attribute of the request object.\n\nHTTP status is stored as an integer in the `status_code` attribute.\n\n## Get a record\nWhen requesting a single record, the `Resource` request object still uses:\n- `api_key`\n- `quiet`\n- `timeout`\n- `attempts`\n- `endpoint`\n\nIt also takes an `irn` parameter, the specific number for that record within the endpoint. Make sure you've set the correct endpoint - /object/123456 isn't the same as /agent/123456.\n\nThe record's data is stored as a dictionary in the `response_text` attribute of the request object.\n\nHTTP status is stored as an integer in the `status_code` attribute.\n\nGet related records by adding the following parameters:\n- `related` (set to True)\n- `size` (the number of related records to return)\n- `types` (a comma separated list of `type` values, eg `Object,Specimen` or `Person`)\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Python interface for Te Papa's collections API",
"version": "0.1.6",
"project_urls": {
"Homepage": "https://github.com/lucyschrader/askCO"
},
"split_keywords": [
"python",
" museum",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a4ab3bb3f405052cad9e735bfc49f2499afbb820f65dc26dc4709852dc627081",
"md5": "9cd6e508eb8e94fee16628c4b7a36923",
"sha256": "493eef0e1dd5a83b9cea5f40467220a2016aecbd0935b7d31b7a8020a174e209"
},
"downloads": -1,
"filename": "askCO-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9cd6e508eb8e94fee16628c4b7a36923",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6688,
"upload_time": "2024-04-05T01:26:25",
"upload_time_iso_8601": "2024-04-05T01:26:25.170522Z",
"url": "https://files.pythonhosted.org/packages/a4/ab/3bb3f405052cad9e735bfc49f2499afbb820f65dc26dc4709852dc627081/askCO-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "565100446932176d18534c727254ead36e63afdf38534215ddc0012da3ab8015",
"md5": "8c6654e8aea0d62454367378608f0c7c",
"sha256": "b21dcd1e9ac484b5e0a548d23e0441a48d2d1f796c81cd94eb96ac76440c0e67"
},
"downloads": -1,
"filename": "askCO-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "8c6654e8aea0d62454367378608f0c7c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 6427,
"upload_time": "2024-04-05T01:26:26",
"upload_time_iso_8601": "2024-04-05T01:26:26.365593Z",
"url": "https://files.pythonhosted.org/packages/56/51/00446932176d18534c727254ead36e63afdf38534215ddc0012da3ab8015/askCO-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-05 01:26:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lucyschrader",
"github_project": "askCO",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "askco"
}
