Intro

Welcome to SeediQ.net's web api.
This api will allow you to tap into our comprehensive agricultural seed database, and empower you with advanced search functionality utilizing ElasticSearch 2.3.



Search Attributes:

While we have many more datapoints, below is a list of what we currently have enabled for search. Don't see the attribute you need to search on? Let us know and we can quickly enable it for search to meet your needs.

Change product selection to see searchable fields:
  • active_ingredient
    • active_ingredient_edgengram
    • active_ingredient_id
    • active_ingredient_ngram
    • active_ingredient_string
  • catalog_year
    • catalog_year_id
    • catalog_year_int
  • company
    • company_edgengram
    • company_id
    • company_ngram
    • company_string
  • crop_type
    • crop_type_edgengram
    • crop_type_id
    • crop_type_ngram
    • crop_type_string
  • environmental_factors
    • environmental_factors_edgengram
    • environmental_factors_id
    • environmental_factors_ngram
    • environmental_factors_string
  • gdus_to_black_layer
    • gdus_to_black_layer_double
    • gdus_to_black_layer_id
  • gdus_to_mid_pollination
    • gdus_to_mid_pollination_double
    • gdus_to_mid_pollination_id
  • gdus_to_mid_silk
    • gdus_to_mid_silk_double
    • gdus_to_mid_silk_id
  • gdus_to_phy_mat
    • gdus_to_phy_mat_double
    • gdus_to_phy_mat_id
  • gdus_to_pollination
    • gdus_to_pollination_double
    • gdus_to_pollination_id
  • gdus_to_silk
    • gdus_to_silk_double
    • gdus_to_silk_id
  • pest_common_name
    • pest_common_name_edgengram
    • pest_common_name_id
    • pest_common_name_ngram
    • pest_common_name_string
  • protein_name
    • protein_name_edgengram
    • protein_name_id
    • protein_name_ngram
    • protein_name_string
  • region
    • region_edgengram
    • region_ngram
    • region_string
  • relative_maturity
    • relative_maturity_double
    • relative_maturity_id
  • seed_name
    • seed_name_edgengram
    • seed_name_id
    • seed_name_ngram
    • seed_name_string
  • traits
    • traits_edgengram
    • traits_id
    • traits_ngram
    • traits_string

What do the different attribute name endings mean? They largely determine how the data is searched when you query a specific attribute.

  • _id - The unique identifier in our system for a specific value. Ideal for faceted searches where the id is known.
  • _int - Integer values. Can be used with range queries
  • _string - The exact, unmodified value of a text field. Searches against this are case sensistive and require an exact match.
  • _bool
  • _date
  • _ngram - Useful for free text search. This is like a full text search in SQL. The following shows the equivalent between SQL and this API.
    • SQL: WHERE (company LIKE '%Some%' OR company LIKE '%Company%' OR company LIKE '%Name%')
    • This API: company_ngram: 'Some Company Name'
  • _edgengram - Useful for free text search. This is equivalent for putting a wildcard on the end of your phrase in SQL. The following shows the equivalent between SQL and this API.
    • SQL: WHERE company like 'Some Company Name%'
    • This API: company_edgengram: 'Some Company Name'
  • _geo - A polygon formed of latitude/longitude points. This can be used to determine which seeds have a growing region that include a specific point.
    Please note:
    • When querying a point in the "Simple" search, the format is "field_name_geo=latitude,longitude" in the query string.
    • In using the "Standard" search, it is formatted [longitude,latitude] in keeping with the GeoJson specification used by ElasticSearch. This orders longitude and latitude opposite of most other systems.
    • This is a new feature and there is minimal data for this as of its 1/25/17 release.

Endpoints


Simple Search

/api/{entityType}/SimpleSearch

Examples:

In the path above, {entityType} is the type of entity you are currently searching for. An example is "seeds".

Simple search allows for querying via the url's query string parameters (parameters in bold)

  • Paging
    • Page - The page number, starting at 1.
    • PageBy - The number of results returned per page
  • Searching / Filtering on Attribute values
    • Use any of the attributes specified above with the type ending specified. For example, to search companies, you would need to use "company_edgengram", "company_id", "company_ngram", or "company_string"; and not the base attribute name of "company".

      If querying a field ending in "_geo", the value should be a point, defined by latitude/longitude values in decimal format. Ex. region_geo=39.809860,-98.555183
  • Faceting
    • Facets are a list of (ValueId, ValueName, Count) for a list of values related to a result set. For example, if you query for seeds by a certain company, and what to know how many of each crop type there are, you would facet on Crop Type and receive a facet result like the following:
      Id Name Count
      16354 Corn 8829
      18909 Soybeans 4781
      20240 Wheat 189
    • FacetAttributes - Attributes you want to get a list of facets for. This takes a comma delimited list of attribute names (see list above)
    • FacetMaxSize - The default is 10; and only the top 10 values with the highest counts will be returned. To return more facet values, increase this number.
  • Geo / Map Results
    • IncludeRegionIds - possible values are true/false.

      Note: If you set this value to true, but your account hasn't been granted access to the Geo based data; you will receive an error message stating that.

      Setting this value to true will cause RegionIds to appear in the result set for any "Val" that has a geographic region defined. These RegionIds can be used in one of two ways:
      1. You can use the RegionId to pull down a .png map of the region.
        Two image sizes are available:
        1. 320x320 - /files/RegionMapImages/[ReplaceWithRegionId]-320x320.png
        2. 640x640 - /files/RegionMapImages/[ReplaceWithRegionId]-640x640.png
      2. If you need a larger or interactive map, you can use the RegionId to get the list of lat/long points that define the region by using the "IncludeRegionCoordinates" param and generate it usings your preferred mapping service.
      Click to view example of result containing RegionId
      {
        "ResultEntities": {
          "Seeds": {
            "Entities": [
              {
                "Id": 18887,
                "Attributes": [
                  {
                    "Id": 1474,
                    "Name": "Seed Name",
                    "AttributeCategoryId": 2,
                    "Vals": [
                      {
                        "Id": 30562,
                        "Name": "0140",
                        "Code": "0140",
                        "Desc": "",
                        "DisplayOrder": 1000
                      }
                    ]
                  },
                 ..................................
                  {
                    "Id": 2090,
                    "Name": "Region",
                    "AttributeCategoryId": 16,
                    "Vals": [
                      {
                        "Id": 66382,
                        "Name": "SOUTHEAST",
                        "DisplayOrder": 1000,
                        "RegionId": 31   <------ this param, IncludeRegionIds, causes this property to appear
                      }
                    ]
                  }
                ],
                "Score": 5.493098,
                "nameAttributeId": 1474,
                "nameValueId": 30562
              },
              ...............
      
    • IncludeRegionCoordinates - possible values are true/false.

      Note: If you set this value to true, but your account hasn't been granted access to the Geo based data; you will receive an error message stating that.

      The "Region" property on the response object will be populated with a list of Regions. Each Region will include the RegionId and a list of lat/long coordinates.
      Important!: This parameter will have no effect if the "IncludeRegionIds" parameter is not also set to true.
      Click to view example JSON Region List
       "Regions": [
          {
            "RegionId": 31,
            "Coordinates": [
              {
                "Latitude": 40.92679481100803,
                "Longitude": -96.1864024400711
              },
              {
                "Latitude": 41.784420075195435,
                "Longitude": -83.7059336900711
              },
              {
                "Latitude": 37.66295028771148,
                "Longitude": -75.2684336900711
              },
              {
                "Latitude": 34.97240036953011,
                "Longitude": -76.0594493150711
              },
              {
                "Latitude": 32.041607605532434,
                "Longitude": -80.3660899400711
              },
              {
                "Latitude": 29.626951045325445,
                "Longitude": -80.6297618150711
              },
              {
                "Latitude": 26.99649215455073,
                "Longitude": -78.9598399400711
              },
              {
                "Latitude": 24.142743274310277,
                "Longitude": -80.3660899400711
              },
              {
                "Latitude": 27.153010072515,
                "Longitude": -83.1785899400711
              },
              {
                "Latitude": 29.779635098260528,
                "Longitude": -83.8817149400711
              },
              {
                "Latitude": 29.24422865436993,
                "Longitude": -94.0770274400711
              }
            ]
          },
          {
            "RegionId": 32,
            "Coordinates": [
              {
                "Latitude": 48.528246635432865,
                "Longitude": -125.5418711900711
              },
              {
                "Latitude": 48.47000755130925,
                "Longitude": -123.6082774400711
              },
              {
                "Latitude": 49.16446497438619,
                "Longitude": -123.6082774400711
              },
              {
                "Latitude": 49.450985625884336,
                "Longitude": -103.5692149400711
              },
              {
                "Latitude": 49.450985625884336,
                "Longitude": -97.1531993150711
              },
              {
                "Latitude": 41.19188279029722,
                "Longitude": -95.6590586900711
              },
              {
                "Latitude": 37.24432275001262,
                "Longitude": -93.7254649400711
              },
              {
                "Latitude": 34.97240036953011,
                "Longitude": -93.9012461900711
              },
              {
                "Latitude": 29.167511390070658,
                "Longitude": -93.0223399400711
              },
              {
                "Latitude": 28.087489128830327,
                "Longitude": -96.7137461900711
              },
              {
                "Latitude": 26.05283471091712,
                "Longitude": -97.1531993150711
              },
              {
                "Latitude": 27.153010072515,
                "Longitude": -100.0535899400711
              },
              {
                "Latitude": 29.167511390070658,
                "Longitude": -101.6356211900711
              },
              {
                "Latitude": 28.62888937223068,
                "Longitude": -103.1297618150711
              },
              {
                "Latitude": 31.443660927778843,
                "Longitude": -106.9969493150711
              },
              {
                "Latitude": 31.29357263490201,
                "Longitude": -107.7000743150711
              },
              {
                "Latitude": 31.29357263490201,
                "Longitude": -110.9520274400711
              },
              {
                "Latitude": 32.041607605532434,
                "Longitude": -117.6317149400711
              },
              {
                "Latitude": 33.665839325843834,
                "Longitude": -120.0047618150711
              },
              {
                "Latitude": 36.04554562636095,
                "Longitude": -122.2020274400711
              },
              {
                "Latitude": 39.17776854099664,
                "Longitude": -124.4871836900711
              },
              {
                "Latitude": 41.587509876092014,
                "Longitude": -124.8387461900711
              },
              {
                "Latitude": 43.91055723664941,
                "Longitude": -124.9266368150711
              },
              {
                "Latitude": 45.34905672720494,
                "Longitude": -124.4871836900711
              },
              {
                "Latitude": 46.99224350989184,
                "Longitude": -124.4871836900711
              }
            ]
          }
        ],
                                          
      Using these two parts together, when you come across a region id, you can reference the region id from the list to get the latitude and longitude values.
  • Other
    • Sort - Attributes you want to sort on. Format "attribute_name:dir,attribute_name2:dir"
      • attribute_name - Any of the attribute names listed above. This requires the use of a attribute name with an "_int" or "_string" type ending on it. Another valid sort option is "_score", which will order based on how well the results matched your query.
      • dir - "asc" or "desc"
    • IncludeRelatedEntites - possible values are true/false.
      This will cause a seperate list of related entities to be included in the response. For example, a seed is manufacturered by a company. To include that company's full information in the response, just set this parameter to true. If you are needing that extra data, using this flag will make your application faster by reducing the number of requests to this api.

Simple Search Export

/api/{entityType}/SimpleSearchExport

In the path above, {entityType} is the type of entity you are currently searching for. An example is "seeds".

This query uses the same query logic as the "Simple Search" endpoint, but instead returns a .csv file with matching records. Please reference the Simple Search Endpoint for query instructions.

Note: this endpoint has not yet been included in the .NET, Php, and Java SDKs.

Examples:


Standard Search

/api/{entityType}/Search

In the path above, {entityType} is the type of entity you are currently searching for. An example is "seeds".

Standard search exposes the full power of this API. It allows for much more complex queries and use cases, pushing the load from your server to ours.

Click here to access our "Query Builder" and get started building test queries / exploring the data. Please note, this requires an account to access. To acquire a demo account free of charge, please contact us at info@seediq.net.


Get Entity(ies)

/api/{entityType}/get_entities/{commaDelimitedListOfEntityIds}

This endpoint allows you to get a specific entity, or list of entities.

Query Params

  • IncludeRelatedEntites - possible values are true/false. This will cause a seperate list of related entities to be included in the response. For example, a seed is manufacturered by a company. To include that company's full information in the response, just set this parameter to true. If you are needing that extra data, using this flag will make your application faster by reducing the number of requests to this api.

Get Modified Entity(ies)

/api/{entityTypeName}/modified_since/{modifiedSinceDate}

This endpoint will retreive a list of entities ids that have changed since the specified date; and will include new, updated, or deleted entities that you have access too.
**Please note, this is a slow running query.

Query Params

  • modifiedSinceDate - This must be in ISO 8601 format (YYYY-MM-DD). Ex. '2016-01-26'

The "Action" property in the result can be "CREATE", "UPDATE", "DELETE", "MERGE".

  • CREATE
  • UPDATE
  • DELETE
  • MERGE

    If this action is returned, then view the "MergedIntoEntityId" property of the "EntityChange" item.
    It will contain the entityId that the record as been merged into.

    Use case: SeediQ located a duplicate seed record and merged them.


Get Attribute(s)

/api/{entityTypeName}/get_attributes

This endpoint will retreive a list of all attributes in the database on a per entity type basis.


Create/Update Seed

api/{entityTypeName}/create_update

This endpoint allows you to submit new or updated seed information.

If a seed already exists with the same name, it will be matched, and your updates will be applied. Some fields allow for multiple values, and others a single value.

When a new seed is added, it will only be available to the service account who added it. SeediQ staff is notified of all create/update requests, and will review new entries. Once an entry has been reviewed, it will be made available to all clients.

Example Json Request to create/update a corn variety called "SomeTestSeedVarietyName"
{
    "Attributes":[
        {
            "AttributeName":"Seed Name",
            "Value":"SomeTestSeedVarietyName"
        },
        {
            "AttributeName":"Company",
            "Value":"CROPLAN"
        },
        {
            "AttributeName":"Crop Type",
            "Value":"Corn"
        },
        {
            "AttributeName":"Catalog Year",
            "Value":"2015"
        },
        {
            "AttributeName":"Relative Maturity",
            "Value":"110"
        },
        {
            "AttributeName":"Traits",
            "Value":"RR2"
        },
        {
            "AttributeName":"Crop Sub-Type",
            "Value":"Sweet Corn"
        }
    ]
}
                        

Implementation


SeediQ SDK / Sample Websites

We support SDKs for three languages: .NET (C#), Java, and PHP.

Overiew

In each of the SDKs, you'll find a fully functional website demoing an expected use case.

The sample websites make use of the "SeediQ.API.Client" class, which has a function that correlates to each webservice endpoint.

There is also a library of Request / Response objects contained in the "SeediQ.ServiceModels" namespace / package.

Downloads

  • SeediQ .NET SDK

    The example website project uses Visual Studio 2013. You may have to upgrade the solution if you're using a newer version of visual studio.

    This solution includes three projects:

    • SeediQAPI - Contains the "Client" class, which wraps each endpoint.
    • ServiceModels - Contains the Request / Response objects.
    • SeediQ-dotNET-sample - A sample MVC website that demonstrates how to use the "SeediQ.API.Client" class along with the various Request / Response objects in the "SeediQ.ServiceModels" namespace.

    The config settings for the demo site are located in the "SeediQ-dotNET-sample" project's web.config file, which is where you'll enter your SeediQ Service Account credentials.

  • SeediQ Java SDK

    The example website project uses Netbeans, and runs on it's built in Glassfish server.

    The relevent packages are located in "SeediQ-Client-Java\java_sample_website\src\main\java\SeediQ""

    • API - Contains the "Client" class, which wraps each endpoint.
    • Helpers - Some helper functions.
    • ServiceModels - Contains the Request / Response objects.

    The config settings for the demo site are located in the same folder in the "Configuration.java" class, which is where you'll enter your SeediQ Service Account credentials.

    The rest of the classes in that directory are servlets, which demonstrate use of the above libraries.

  • SeediQ PHP SDK

    The example website project runs on Apache with php5. A Vagrant file is included, which can be used to boot up a virtual machine which runs the website on port 8081. The sample website will be accessable at "http://127.0.0.1:8081/". Please note: This requires Oracle's Virtual Box and Vagrant be installed.

    The relevent packages are located in "SeediQ-Client-PHP\seediq_php_sample\SeediQ"

    • API - Contains the "Client" class, which wraps each endpoint.
    • ElasticSearchQueryExamples - If using the "Standard" search, which requires an ElasticSearch query, this folder contains some examples of how you could construct your query.
    • ServiceModels - Contains the Request / Response objects.

    The config settings for the demo site are located in "SeediQ-Client-PHP\seediq_php_sample\Settings.php", which is where you'll enter your SeediQ Service Account credentials.

    Navigating back up one level to SeediQ-Client-PHP\seediq_php_sample directory and you will find the classes which demonstrate the use of the above libraries.


Custom Implementation

If your shop does not use one of the lanuages above, you can interface directly with this api.

The various endpoints are documented in the left column of this page, and authentication information is listed below.

Authentication

This api is secured using https and HTTP Basic Authentication.

To make a request using basic authentication, you'll need to add an "Authorization" header.

Authorization: Basic dGVzdDp1c2Vy

In the above example, "dGVzdDp1c2Vy" is the value generated by combining the username and password with a colon between them, and then base64 encoding.

For example, if the username is "test" and the password is "user", then you'd combine them to produce "test:user", and then base64 encode that string. The result would be "dGVzdDp1c2Vy"

Base64 encode your "username:password" »


Formats

This api supports JSON and XML, with the result being determined by the "Accept" header.

Json

Accept: application/json

Xml

Accept: application/xml

System Info

Current Index: seediq_prod_63