# SHARE Search
Visit the SHARE search API endpoint [here](https://osf.io/api/v1/share/search/)
For security reasons, unencrypted HTTP access is not permitted.
The ```/api/v1/share/search/``` endpoint supports both GET and POST requests. The data returned by both endpoints is JSON, by default in the format:
```json
{
"count": # of metadata documents found,
"results": list of documents corresponding to the SHARE schema,
"time": Amount of time the query took
}
```
Both endpoints have the following query parameters in common:
#### count
If the ```count``` parameter is defined, all other parameters except for ```q``` are ignored. The ```results``` field of the response is always empty, and the ```count``` field corresponds to the number of matches for the query.
#### raw
If the ```raw``` parameter is defined, the results of the request will be the raw Elasticsearch results, rather than the processed version normally returned. The Elasticsearch results will usually be of following form (Note: for most use cases, the filtered form of the API will be adequate, and will not require a knowledge of Elasticsearch internals):
```json
{
"time": # of seconds the query took (total),
"hits": {
"hits": [{
"_score": relevance score of document,
"_type": Specifies type within the SHARE index,
"_id": A unique identifier for the document within the type,
"_source": a JSON object corresponding to the SHARE schema,
"_index": index the data resides on (share)
}, ..],
"total": # of documents found,
"max_score": maximum relevance score of a document
},
"_shards": {
"successful": # of shards that successfully completed the query,
"failed": # of shards that failed to complete querying,
"total": failed + successful
},
"took": time spent on the Elasticsearch portion of query,
"timed_out": Whether or not the query timed out
}
```
## GET
The get API also accepts the following query parameters:
#### q
The ```q``` paramater can be any valid [Lucene query](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html) string. Some examples are below:
##### Filtering by keyword
```
q=NOT keyword
```
#### from
```from``` represents the starting index of the search. Indexing begins at 0. If you set the ```size``` to 100, to page through the results, you would increase your ```from``` by increments of 100. Defaults to 0.
#### size
```size``` determines the number of results returned at a time. Defaults to 10.
#### sort
The ```sort``` parameter determines what value the results are sorted on. If not provided, it defaults to sorting based on the relevance score computed by Elasticsearch.
#### Bringing it all together
In the end the above paramaters are combined into a single Elasticsearch query, of the following form:
```json
{
"query": {
"query_string": {
"default_field": "_all",
"query": q,
"analyze_wildcard": True,
"lenient": True
}
},
"from": start,
"size": size,
"sort": [{
sort: "desc"
}]
}
```
### Examples
Below are a few valid GET queries using curl:
```curl
curl -XGET 'https://osf.io/api/v1/share/search/?q=(shareProperties.source:asu) AND (title:"fish")&sort=providerUpdatedDateTime'
```
This query will give you the the results for the query matching on documents from the Arizona State Digitial Repository whose titles mention "fish", sorted by the date they were last updated by the original provider.
