Agroknow Search API

Requests

The base URL of the API is:

http://<DOMAIN>/v1
(it should change to api.agroknow.com later)
You must enter your 32-character API key after the &api_key= parameter in every request you make, including the examples below. Learn how to request one.

Resource Types

When you formulate a REST query, you have to decide which resource type you want. The resource type is the first word in your query and determines the format of the response data. The resource types currently offered are described below.

akif

AgroKnow akif type is a data model to represent agricultural data.

The RESTful URL to request data from the akif resource begins:

http://<DOMAIN>/v1/akif

agrif

AgroKnow agrif type is a data model to represent bibliographical data.

The RESTful URL to request data from the agrif resource begins:

http://<DOMAIN>/v1/agrif

Feature Outline

Query features can be broken into two sections: What do you want? and How do you want it?

What do you want?

How do you want it?

Putting it all together

 

Features

Simple search

This is just a keyword search against all the text fields. If don't know anything about the fields, but you know you want fossil, use the q parameter.

Example:

http://<DOMAIN>/v1/akif?q=fossil&api_key=

(items with fossil anywhere in any field)

http://<DOMAIN>/v1/akif?q=*&api_key=

(all items)

Searching within specific fields

You don't know what you want, but you know it has to have oil in the english title. It doesn't just have to be the title, though. You can search for terms within any textual field except:

You do not need the q parameter when searching within a specific field. Use the field's name as a URL query string parameter instead.

You can combine specific field searches with simple search. You can also combine multiple field-specific searches. When combining field q parameters, separate them with an ampersand (&). These combinations are exclusive, meaning that result items fulfill all simple and field-specific criteria.

Examples:

http://<DOMAIN>/v1/akif?set=KEEVOSH&api_key=

(items with KEEVOSH anywhere in the set field)

http://<DOMAIN>/v1/akif?languageBlocks.en.title=oil&api_key=

(items with oil anywhere in the languageBlocks.en.title field)

Multiple:

http://<DOMAIN>/v1/akif?expressions.language=en&languageBlocks.en.description=sea&api_key=

(items with en in the expressions.languages and sea in the languageBlocks.en.description)

Field & simple:

http://<DOMAIN>/v1/akif?set=ASETVALUE&q=zebra&api_key=

(items with ASETVALUE in the set and zebra in any field.)

Boolean:

http://<DOMAIN>/v1/akif?status=pending+OR+active&api_key=

(items with active or pending in the status.)

Temporal searching

The Agroknow Search API understands dates. Combine that with the fielded search above, and you've got a pretty spiffy way of finding records that have fields that fall before, after, and between dates.

The following examples search the creationDate field which is the time an akif or agrif document was created.

Examples:

http://<DOMAIN>/v1/akif?creationDate=1910-01-01&api_key=

(items that were created on 1910)

Fetching specific items

Say you already have the set and id for the item you want, and you're just looking to get the rest of the metadata for that item. Simply add the set/id to the end of the items request. Bonus: You can search for multiple id's in the given set by separating the ids with a comma (,).

Example:

http://<DOMAIN>/v1/akif/SECRMICRO/20296?api_key=

(item with the given set and id)

Sorting results

Sort stuff using the sort_by parameter. We’ll sort stuff in ascending order by default, but if you'd like to flip things, set the sort_order parameter to desc.

Examples:

http://<DOMAIN>/v1/akif?q=fossil&sort_by=languageBlocks.en.title&api_key=

(items with fossil in any field, sorted by the languageBlocks.en.title)

http://<DOMAIN>/v1/akif?q=fossil&sort_by=creationDate&sort_order=desc&api_key=

(items with fossil in any field, sorted by creationDate)

http://<DOMAIN>/v1/akif?q=sea&sort_by=languageBlocks.en.title&api_key=

(items with sea in any field, sorted by their english title)

Faceting results

Facets tell you the most common values for certain fields in a collection of items. We return a couple different types of facets depending upon the field you're looking for. For date fields, we'll send back facets of type date_histogram (which is what it sounds like). For complex text fields, we'll break it down for you into a terms type. For simple text fields, we'll also send back a terms type but with unadulterated values. And for geographic types, we'll give you a geo_distance type.

Examples:

Basic:

http://<DOMAIN>/v1/akif?facets=set&api_key=

Multiple:

http://<DOMAIN>/v1/akif?facets=languageBlocks.en.title,set&api_key=

No Docs:

http://api.dp.la/dev/items?facets=set&page_size=0&api_key=

Facet Limit:

http://<DOMAIN>/v1/akif?facets=set&facet_size=3&api_key=

 

Pagination

By default, we'll give you 10 items. If that's not enough, you can get the next ten items incrementing the page parameter (it's one-indexed). If that's still not enough, you can pull more items per page by using the page_size parameter (we'll limit you to 100 items per page because greediness is a vice).

Examples:

http://<DOMAIN>/v1/akif?q=fossil&page_size=2&api_key=
http://<DOMAIN>/v1/akif?q=sea&page_size=25&api_key=
http://<DOMAIN>/v1/akif?q=sea&page_size=25&page=3&api_key=

 

Complex Queries

Let's get this APIarty started.

Examples:

http://<DOMAIN>/v1/akif?q=sea&languageBlocks.en.title=africa&api_key=

(items with both sea in any field and africa in the languageBlocks.en.title)

http://<DOMAIN>/v1/akif?languageBlocks.en.description=sea+OR+africa&page_size=25&api_key=

(the first 25 items with either sea or africa in the languageBlocks.en.description)