SODA API: Views Service

The ViewsService allows you to retrieve and manipulate metadata about datasets and views, as well as to query for datasets and views that match given search criteria. It also allows you to create, read, update, and delete rows of data from datasets and views.

Clients are granted permissions to read, add to, modify, and delete rows from views based on the permissions the user that they have authenticated as. For example, any user can read from a public dataset, but only the owner or a sharee of a private dataset can view or modify data. For more details on how to authenticate, see the documentation on the AuthenticationService.

/api/views

• GET *

  Compliance Level: This method is required by the SODA standard

  Query for views that match a given set of criteria. The resulting output will include summary information about the views that matched your query.

  Additional query parameters restrict the search further (as a boolean "AND").

  This is deprecated in favour of the search service.

  Parameters:

  • categorystringFilters for views matching this category
  • namestringFilters for views containing this text in their name
  • descriptionstringFilters for views with this text in their description
  • tagsstring[]Filters for views matching these tags
  • fullstringFilters for views with this text in the metadata or content
  • countbooleanExecutes the query with the given parameters and only returns the total number of rows, and ignores the limit parameter
  • limitintegerTotal number of results to return, up to 200 at a time
  • pageintegerPage number to retrieve additional pages of results

  Responds with:

  • View[]

  Examples:

  Query for views that match given search criteria:

  > curl "https://data.cms.gov/api/views.json?name=Favorite&pct;20Wines&max_results=5"
  > curl "https://data.cms.gov/api/views.json?tags=wine
  

/api/views/(view ID)

• GET

  Compliance Level: This method is required by the SODA standard

  Retrieve a specific view by ID.

  Parameters:

  • view IDstring (required)The ID of the view to retrieve

  Responds with:

  • View

  Examples:

  Retrieve metadata about a view using its ID:

  > curl --cookie cookies.txt https://data.cms.gov/api/views/6nt6-jwts.json
  

/api/views/(view ID)/columns

• GET

  Compliance Level: This method is required by the SODA standard

  List all of the columns in a view.

  Parameters:

  • view IDstring (required)The view ID

  Responds with:

  • ViewColumn[]

  Examples:

  Retrieve metadata about all of the columns on a given view:

  > curl https://data.cms.gov/api/views/6p3t-a73v/columns.json
  [ {
    "id" : 65,
    "name" : "Name ",
    "dataTypeName" : "text",
    "position" : 2,
    "renderTypeName" : "text",
    "tableColumnId" : 68,
    "width" : 105,
    "format" : {
      "formatting_option" : "Plain",
      "datatype_name" : "Text"
    }
  },
  ...
  ]
  

/api/views/(view ID)/columns/(column ID)

• GET

  Compliance Level: This method is required by the SODA standard

  Retrieve details about a particular column.

  Parameters:

  • view IDstring (required)The view ID
  • column IDinteger (required)The ID of the column to retrieve

  Responds with:

  • ViewColumn

  Examples:

  Retrieve metadata about a particular columns on a given view:

  > curl https://data.cms.gov/api/views/6p3t-a73v/columns/65.json
  {
    "id" : 65,
    "name" : "Name ",
    "dataTypeName" : "text",
    "position" : 2,
    "renderTypeName" : "text",
    "tableColumnId" : 68,
    "width" : 105,
    "format" : {
      "formatting_option" : "Plain",
      "datatype_name" : "Text"
    }
  }
  

/api/views/(view ID)/columns/(column ID)/sub_columns

• GET

  Compliance Level: This method is a Socrata extension to the SODA standard

  List all of the sub-columns for a given nested table.

  Parameters:

  • view IDstring (required)The ID for the view
  • column IDinteger (required)The ID of the parent column

  Responds with:

  • ViewColumn[]

  Examples:

/api/views/(view ID)/files/(file ID)

• GET

  Compliance Level: This method is a Socrata extension to the SODA standard

  Retrieve a file that has been attached to a view.

  Parameters:

  • file IDstring (required)The ID of the file to download
  • view IDstring (required)The ID of the view the file is attached to
  • filenamestringThe filename to which to present to the user
  • sizeDimensionThe size to deliver, if the file is an image

  Examples:

  Retrieve a file that has been attached to a view:

  > curl --cookie cookies.txt http://data.cms.gov/api/views/6nt6-jwts/files/90646584-F950-4895-9354-E8981D30DED4 > image.jpg
  

/api/views/(view ID)/rows

• GET *

  Compliance Level: This method is required by the SODA standard

  Retrieve multiple rows from a view as nested arrays instead of in the expanded form. By default this will return all the rows in the view, but you can limit the number of rows returned with max_rows or request only specific rows using ids. You can also request only row IDs by passing row_ids_only. You must have read permissions on the view in order to access this resource.

  Parameters:

  • view IDstring (required)The ID of the view that contains the row
  • row_ids_onlybooleanIf true, the service will only return row IDs
  • max_rowsintegerLimit the number of rows returned
  • include_ids_afterintegerInclude this number of rows, after which only row IDs are returned.
  • searchstringRun a full text search on the view and only return rows/ids that match
  • metabooleanIf set to 'true', will write the view object. Only valid if rendering JSON. Default is true.
  • as_hashesbooleanIf set to 'true', write fields in hash format. Otherwise, write fields in array. Only valid if rendering JSON. Default to false (array).
  • exclude_system_fieldsbooleanIf set to 'true', do not return system fields like row id. Only valid if rendering JSON. Default to false.
  • unwrappedbooleanIf set to 'true', return just array or rows with no outer object. Only valid if rendering JSON. Default to false.
  • most_recentbooleanIf set to 'true', return only the most recent rows added to the dataset. Only valid if rendering RSS. Default to true.
  • access_typeAccessChannelvalid values are PRINT, EMAIL, API, RSS, WIDGET, DOWNLOAD, WEBSITE

  Examples:

  Retrieve rows from a view as JSON and as CSV:

  > curl --cookie cookies.txt https://data.cms.gov/api/views/6nt6-jwts/rows.json
  > curl --cookie cookies.txt https://data.cms.gov/api/views/6nt6-jwts/rows.csv
  

/api/views/(view ID)/rows/(row ID)

• GET

  Compliance Level: This method is required by the SODA standard

  Retrieve the expanded representation of a particular row by ID. You must have read permissions on the view in order to access this resource.

  Parameters:

  • view IDstring (required)The ID of the view that contains the row
  • row IDstring (required)The ID of the row to retrieve

  Responds with:

  • Row

  Examples:

  Retrieve a particular row from a view, and then update it:

  > curl --cookie cookies.txt https://data.cms.gov/api/views/6nt6-jwts/rows/F2620731-F24F-469C-8984-4D600F6E7FC5.json > row.json
  > cat row.json
  {
    "_uuid" : "F2620731-F24F-469C-8984-4D600F6E7FC5",
    "Text Column" : "New Value",
    "Number Column" : 67,
    "Date Column" : 1239345679
    "_tags" : [ ]
  }
  
  

/api/views/(view ID)/tags

• GET *

  Compliance Level: This method is a Socrata extension to the SODA standard

  Allows you to retrieve tags for a view

  Parameters:

  • view IDstring (required) 

  Responds with:

  • string[]

  Examples:

  Retrieve the row tags for a given view:

  > curl --cookie cookies.txt https://data.cms.gov/api/views/6nt6-jwts/tags.json
  [ "tags", "are", "cool" ]
  

/api/views/(view ID)/user_tags

• GET *

  Compliance Level: This method is a Socrata extension to the SODA standard

  Allows you to retrieve tags for a view

  Parameters:

  • view IDstring (required) 

  Responds with:

  • UserTag[]

* This method is not yet currently finalized and is subject to change

This API documentation is licensed as Creative Commons By-Attribution 3.0.

Current Revision: 07e2e8a (Fri Feb 15 14:53:30 PST 2013)