API DOCUMENTATION

The MATTERS site contains data collected from a number of sources stored in one convenient database. To help users make the most of all of this data, MATTERS has provided an API. This tool is designed to provide users access to the data points in the MATTERS database in a quick and efficient manner by making use of the API calls. This documentation will show you how to use the MATTERS API in order to properly access these data points. All data returned will be in a JSON format.



To start, a valid request for accessing the API will look like the following: {website}/api/{method}?{paramName}={paramValue}&{paramName}={paramValue}



Below we will explain the methods and parameters that can be used to get data from the site, and valid format for the parameter values



  1. Methods
  2. Data
  3. Parameter Names
  4. API Key
  5. State
  6. Metric
  7. Year
  8. Examples


Methods:

Data

  • URL Path: matters.mhtc.org/api/data

This method can be used to access any of the data points from the site



Parameter Names

The following are the potential parameter names that can be used along with the data method to access data for certain states, years, and metrics.



API Key

The API key is the key associated with the person trying to access the data. You can get your personal API key by contacting us. You must be a registered user with your email address in the system in order to receive an API key. We will respond to the email with your specific API key that you can use to access the data points.



  • URL Path: matters.mhtc.org/api/data?&apiKey=yourKey
  • Validation: the API key is used to check if a user is allowed access to the data he wishes to return. For this reason, you must always include the API key parameter followed by your unique key.


State

State is used to choose which state(s) you would like to access the data of. A list of states and their information can be found by going to: matters.mhtc.org/api/states?apiKey=yourKey



  • URL Path: matters.mhtc.org/api/data?state={paramValue}


  • Valid {paramValues}:
    • * : this parameter is to be used to represent all states. This is the default setting if no state is given.
    • peer : this parameter will select data for all peer states
    • {state abbreviation}: giving a single state's two letter abbreviation (ex: {MA} for Massachusetts) will return data for that one state
    • {state abbreviation, state abbreviation, ...}: giving a list of proper state abbreviations (ex: {MA, FL}) will return the data for all states listed


Metric

Metric is used to choose which metric(s) for the states chosen that you would like to access the data of. A list of metrics and their information can be found by going to: matters.mhtc.org/api/metrics?apiKey=yourKey



  • URL Path: matters.mhtc.org/api/data?metric={paramValues}


  • Valid {paramValues}:
    • * : this parameter is to be used to represent all metrics. This is the default setting if no metric is given.
    • {metric ID}: giving a valid metric ID number (ex: {19}) will return the data for the metric associated with that ID number
    • {metric ID, metric ID, ...}: giving a list of metric IDs (ex: {19, 20}) will return the data for all metrics listed


Year

Year is used to choose which year(s) for the states and metrics chosen that you would like to access the data of



  • URL Path: matters.mhtc.org/api/data?year={paramValue}


  • Valid {paramValues}:
    • * : this parameter is to be used to represent all years. This is the default setting if no year is given.
    • year: giving a valid year (ex: 2014) will return the data for the specific year chosen
    • {year-year}: giving a range of years (ex: {2010-2014}) will return the data for all years in the range


Examples of valid API requests and what it would return:

EXAMPLE 1.http://matters.mhtc.org/api/data?state={AL}&metric={18}&year=2012&apiKey=yourKey



This would return the data points for Alabama for metric 18 for the year 2012, provided that the user has permission to access this data, as a JSON. Click to show:



EXAMPLE 2. http://matters.mhtc.org/api/data?apiKey=yourKey&state=peer&metric={19}&year=2013



This would return the data points for all peer states for metric 19 for the year 2013, provided that the user has permission to access this data, as a JSON. Click to show: