LittleSis Api Documentation - Version 2

Responses

The API follows many of the conventions of JSON API, but does not implement the entire specification.

All responses are in JSON.

Successful Responses

For singular resources, this will return an object with two fields: data and meta. The meta object contains copyright, license, api version, and other similar information. The data object will have four fields: type, id, attributes, and links.

Type is the type of resource requested: (i.e. entities). Id is the resource's id. Attributes contain the resource attributes. Links contain at least one link to LittleSis where the resource can be viewed.

Structure of response:


{
  data: {
          type: 'resourceType'
          id: '123'
          attributes: { ... }
          links: {
            self: '/link/to/resource'
          }
        },
   meta: { ... }
}

All successful responses will return status code 200

Errors

If an error occurs, the API will return json containing information about the error along with an error status code.

Structure of an error response:


{
  errors: [ {title: 'Details here about the error'} ],
  meta: { ... }
}

Error Status Codes

Status Code	Meaning
400	Missing required param
404	Resource is missing or never existed
410	Resource has been deleted (but once existed)
503	Rate Limit Exceeded

Entity Resources

`/api/entities/:id`

This provides basic information about an entity:

id: Unique numerical ID for entity in LittleSis database.
name: The primary alias (not necessarily unique) of the Entity in LittleSis
blurb: A short phrase or sentence describing the Entity
primary_ext: "Person" or "Org"
summary: A longer bio or summary of the Entity
website: The Entity's website
start_date: The date when the Entity came to exist -- DOB for people, founding dates for orgs
end_date: The date, if any, when the Entity ceased to exist
parent_id: If the Entity is a sub-organization of a parent Entity, the parent's id is stored here
updated_at: The last time the Entity data was updated
types: An array of types (also known as extensions) associated with the entity. i.e. Business, Lawyer
aliases: An array of other names the entity is known as

Entity Extension

`/api/entities/:id/extensions`

Extensions are also known as types. All entities have at least one type -- Organization or Person. Other types include: Business Person, Public Company, Political Candidate, and Professional Associations.

Example request: curl https://littlesis.org/api/entities/1/extensions


{
  "data": [
    {
      "type": "extension-records",
      "id": 1,
      "attributes": {
        "id": 1,
        "definition_id": 2,
        "display_name": "Organization",
        "name": "Org"
      }
    },
    {
      "type": "extension-records",
      "id": 2,
      "attributes": {
        "id": 2,
        "definition_id": 5,
        "display_name": "Business",
        "name": "Business"
      }
    },
    {
      "type": "extension-records",
      "id": 3,
      "attributes": {
        "id": 3,
        "definition_id": 13,
        "display_name": "Public Company",
        "name": "PublicCompany"
      }
    }
  ],
  "meta": {...}
}

add details=TRUE to include additional information that's contained within the extension (not all extensions have additional fields)

Entity Relationships

`/api/entities/:id/relationships`

Relationships this entity has with other entities. The key "data" contains an array of Relationship elements. These requests can also be paginated.

You can find limit the relationships to specific category by including the param "category_id".

Entity Connections

`/api/entities/:id/connections`

Other entities that this entity has a relationship with. The key "data" contains an array of Entity elements. This route accepts the params "category_id" which will only limit connections to those entities that are connected with a relationship of the provided category. The results are sorted by the connected entity link_count

The entity attributes object contains two additional fields -- relationship_id and relationship_category_id

Entity Lists

`/api/entities/:id/lists`

The lists that the entity is on

Example request: curl https://littlesis.org/api/entities/10/lists


{
  "meta": {
    "copyright": "LittleSis CC BY-SA 3.0",
    "license": "https://creativecommons.org/licenses/by-sa/3.0/us/",
    "apiVersion": "2.0"
  },
  "data": [
    {
      "type": "lists",
      "id": 1,
      "attributes": {
        "id": 1,
        "name": "Fortune 1000 Companies (2008)",
        "description": "Fortune Magazine's list of the 1000 US companies with the largest published revenue figures.",
        "is_ranked": true,
        "is_featured": false,
        "updated_at": "2017-02-01T15:46:35Z",
        "short_description": null,
        "entity_count": 1000
      },
      "links": {
        "self": "https://littlesis.org/lists/1-fortune-1000-companies-2008"
      }
    },
    {
      "type": "lists",
      "id": 291,
      "attributes": {
        "id": 291,
        "name": "Top Lobbying Clients in New York State in 2011",
        "description": "\"In 2011, 2,776 unique groups spent money lobbying in New York. The chart found from pages 2 through 97 of this report ranks each of them and compares their spending to 2010 levels.\"\r\n\r\n-NYPIRG, April 5, 2012",
        "is_ranked": true,
        "is_featured": false,
        "updated_at": "2017-04-27T01:33:39Z",
        "short_description": null,
        "entity_count": 96
      },
      "links": {
        "self": "https://littlesis.org/lists/291-top-lobbying-clients-in-new-york-state-in-2011"
      }
    }
  ]
}

Search by name

`/api/entities/search?q=NAME`

This searches our database for entities. The number of the relationships the entity has is used in the ranking algorithm. For instance, searching for 'Bush' will put George Bush before Jeb Bush because the former has more relationships in our database than the latter.

Example response:


{
    "data": [
	{
	  // entity objects are identical to those returned by the /api/entities/:id route
	},
    ],

    "meta": {
	"currentPage": 1,
	"pageCount": 3,
	"copyright": "LittleSis CC BY-SA 3.0",
	"license": "https://creativecommons.org/licenses/by-sa/3.0/us/",
	"apiVersion": "2.0"
    }
}

It will return at most 10 entities at a time. If there are more than 10 results, you can request additional pages by including the param page (page=NUMBER) to the request. Leaving out the param page is the same as requesting page 1

optional parameters

regions (regions=3) filters search search by region
tags (regions=oil) fitlers search results by tags

Relationships

`/api/relationships/:id`

This provides basic information about a relationship:

id: Unique numerical ID for relationship in LittleSis database.
description: A sentence describing the relationship
category_id: Integer between 1 and 12, representing the relationship category
category_name: The category of the relationship
description1: Often the "title", but the precise meaning varies by relationship category
description2:
amount: Amount of the transaction or donation
goods: goods provided
start_date: The date when the relationship started
end_date: The date when the relationship ended
is_current: If the relationship is ongoing. (null = unknown)
entity1_id: ID of the first entity in the relationship
entity2_id: ID of the second entity in the relationship

The response object also includes information on the two entities in the relationship under the key 'included'

Example request: curl https://littlesis.org/api/relationships/297069


{
  "meta": {
    "copyright": "LittleSis CC BY-SA 3.0",
    "license": "https://creativecommons.org/licenses/by-sa/3.0/us/",
    "apiVersion": "2.0"
  },
  "data": {
    "type": "relationships",
    "id": 297069,
    "attributes": {
      "id": 297069,
      "entity1_id": 72489,
      "entity2_id": 28778,
      "category_id": 5,
      "description1": "Campaign Contribution",
      "description2": "Campaign Contribution",
      "amount": 631700,
      "goods": null,
      "filings": 16,
      "updated_at": "2017-07-25T18:18:13Z",
      "start_date": "2004-00-00",
      "end_date": "2016-04-25",
      "is_current": null,
      "description": "Robert Mercer gave money to  Republican National Committee"
    },
    "links": {
      "self": "https://littlesis.org/relationships/297069"
    }
  },
  "included": [
    {
      "type": "entities",
      "id": 72489,
      "attributes": {
        "id": 72489,
        "name": "Robert Mercer",
        "blurb": "Renaissance Tech billionaire, Club for Growth backer",
        "summary": "Robert Mercer, 65, is co-CEO of Renaissance Technologies LLC, a $15 billion hedge fund. The IBM language-recognition whiz-turned-financier brought home $125 million in 2011, making him the 16th highest-earning hedge fund manager, according to Forbes.\r\n\r\nRenaissance Technologies is based in New York City, with additional locations in London and East Setauket, N.Y., where Mercer lives.",
        "website": null,
        "parent_id": null,
        "primary_ext": "Person",
        "updated_at": "2017-09-11T21:48:02Z",
        "start_date": null,
        "end_date": null,
        "aliases": [
          "Robert Mercer"
        ],
        "types": [
          "Person",
          "Business Person"
        ]
      },
      "links": {
        "self": "https://littlesis.org/entities/72489-Robert_Mercer"
      }
    },
    {
      "type": "entities",
      "id": 28778,
      "attributes": {
        "id": 28778,
        "name": "Republican National Committee",
        "blurb": "The Grand Ol' Party",
        "summary": null,
        "website": null,
        "parent_id": null,
        "primary_ext": "Org",
        "updated_at": "2017-10-09T01:09:46Z",
        "start_date": null,
        "end_date": null,
        "aliases": [
          "Republican National Committee",
          "RNC"
        ],
        "types": [
          "Organization",
          "Political Fundraising Committee",
          "Other Campaign Committee"
        ]
      },
      "links": {
        "self": "https://littlesis.org/entities/28778-Republican_National_Committee"
      }
    }
  ]
}