Getting Started

This document aims to get you going with the Knodes API as quickly as possible.

If you run into any issues whatsoever, we are here to help! Email developers@knod.es and we will get to the bottom of it.

Overview

What it is

The Knodes Context API makes it simple and easy to augment your applications with powerful social integration and data analysis. Customers (i.e., you) can link their Knodes customer account to their apps on various social networks. Then, when users connect to your social network apps, you can create corresponding Knodes users by sending their social network access tokens to Knodes.

Once you have a Knodes user, you can tell Knodes to index that user's social data. Knodes will then do a deep index and analysis of the people, locations, companies, schools, and documents in that user's first-degree network and make it fast and simple for you to browse and search against that data.

Once your user is indexed, you can use that index to answer interesting questions, such as:

  • Who do you know in New York City who knows about Venture Capital?
  • Who should you see next time you go to San Francisco?
  • Which people in your network are most engaged with you?
  • Would any of the people you typically go places with be interested in this dance performance?
  • Do you have any classmates that are in finance?

Note: the first time you build a user's index, the process will take 20-30 minutes, depending on network size and system load. We hate to make you wait, but good things take time.

What it isn't

The Knodes API absolutely cannot be used for ad targeting, or for any invasion of user privacy. See our Rationale for Existence for more detail on guiding principles.

Privacy

The safety privacy of your and your users' data is our #1 priority. We never provide your data or your users' data to anyone but you and you alone via this API, and we comply 100% with all usage agreements set forth by the various social networks. You retain license to any data obtained via your social network applications. For more info please read our Terms of Service and Customer Agreement.

Getting Going

Credentials

You will need customer credentials to use the Knodes API. If you have not already received API credentials, you can request access here.

Resources

We're just beginning to let folks into the Knodes API to check it out, so please bear with us if you find the occasional rough edge. That said, we already have a few bodacious resources to aid your development:

Customer Portal The dashboard for your Knodes Account. Lots of fun tools and more added all the time. Access it here.
Test Harness Powerful utility for running requests against the Knodes API. You can access it directly here.
Our Team. All the time. Your success is our highest priority. If something isn't working, or if something could just work better, please email us at developers@knod.es, any time, day or night.

Clients

Language-specific API clients are in the works! In the meantime, Knodes is a well-behaved JSON REST API, so it should work with most generic REST clients.

Want to make Knodes fame, get great schwag, and receive other creative forms of adulation and renumeration? Build a client and tell us about it!

Hello, World

To verify your user credentials are working properly, make a call to the /customers endpoint to view your customer record:

https://api.knod.es/customers.json?customer_id=:CUSTOMER_ID&customer_secret=:CUSTOMER_SECRET

Sample output:

 {
  "id": "4fa1751f8c50d8ec73000000",
  "admission_policy": "open",
  "name": "Demo Tester",
  "network_apps": {
    "facebook": "256183204478907",
    "twitter": "1RX0xudmN0p7ZUdeCiZgA",
    "foursquare": "0OH0SJUEXPBBV0OC0GAPJVWMYC5P2YNXEVM1ZWGGGYHRGBNQ",
    "linkedin": "n35925e6w5qy"
  },
  "links": [
    {
      "rel": "self",
      "href": "https://api.knod.es/customers/4fa1751f8c50d8ec73000000"
    },
    {
      "rel": "users",
      "href": "https://api.knod.es/users"
    }
  ]
} 

This call in the test harness.

API Docs for this call.

Note: The first time you execute this command, you may be surprised to see a list of network applications before you've done anything. We setup all new accounts in Demo Mode. While in Demo Mode, your customer account is tested to our demo social network applications. Read on for more info on why that's cool.

Beyond Hello, World

Once you've verified your credentials are working correctly, you probably want to do something a little more interesting. To help get you going, we setup all new accounts in Demo Mode. That means your account is connected to our demo social network apps, and you have acccess to a speicial demo user, a good friend of Knodes named Joe Blowski.

Demo Mode enables you to use the User Connector to connect test users to your account. When you eventually go live using your own network apps, network security constraints will require that you implement user authentication on your own site and then submit user tokens to Knodes via /users/connect.

Of course, if you already have your own network applications and want to get going right away with them, you can disable Demo Mode in the Customer Portal and connect your own accounts via /customers/connect.

Read on for some sample queries you can run against your demo account.

Sample Queries

List Users

List all your users. In demo mode, you will see one pre-seeded demo user.

https://api.knod.es/users.json?customer_id=:CUSTOMER_ID&customer_secret=:CUSTOMER_SECRET

Sample output:

 [
  {
    "id": "4fa175ea8c50d85c7c000006",
    "status": "ok",
    "ready": "ok",
    "role": "member",
    "networks": {
      "facebook": "100003587048285",
      "twitter": "569355432",
      "foursquare": "27243075",
      "linkedin": "YC8AD7Kkj1"
    },
    "email": "developers@knod.es",
    "name": "Joe Blowski",
    "person": {
      "id": "4fa9a8e8e4b0e1d60db9f345",
      "name": "Joe Blowski",
      "photo_url": "http://api.knod.es/media/4f4251c48c50d87431000019?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "facebook",
          "network_id": "100003587048285",
          "profile_url": "http://facebook.com/",
          "photo_url": "https://graph.facebook.com//picture?type=large",
          "relationship": []
        },
        {
          "network": "twitter",
          "network_id": "569355432",
          "screen_name": "thejoeblowski",
          "profile_url": "http://twitter.com/thejoeblowski",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=thejoeblowski&size=original",
          "relationship": []
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f345"
        }
      ]
    },
    "created": 1335995946,
    "links": [
      {
        "rel": "self",
        "href": "https://api.knod.es/users/4fa175ea8c50d85c7c000006"
      }
    ]
  }
] 

This call in the test harness.

API Docs for this call.

View Person Details

People represent real-world people, while a user is simply a wrapper around some social network account credentials. Most of the action in the API happens at the person level, with a user ID specified only to indicate the user whose network you are querying.

This is the demo user Joe Blowski's associated person record, queried by himself (i.e. by his own user ID).

https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f345.json?customer_id=:CUSTOMER_ID&customer_secret=:CUSTOMER_SECRET&user_id=4fa175ea8c50d85c7c000006

Sample output:

 {
  "id": "4fa9a8e8e4b0e1d60db9f345",
  "name": "Joe Blowski",
  "photo_url": "http://api.knod.es/media/4faa87428e63968d3600000a?w=100&h=100&force=1",
  "engagement_score_me_to_them": 0,
  "engagement_score_them_to_me": 0,
  "networks": [
    {
      "network": "facebook",
      "network_id": "100003587048285",
      "profile_url": "http://facebook.com/knodes.joe",
      "photo_url": "https://graph.facebook.com/knodes.joe/picture?type=large",
      "relationship": []
    },
    {
      "network": "twitter",
      "network_id": "569355432",
      "screen_name": "thejoeblowski",
      "profile_url": "http://twitter.com/thejoeblowski",
      "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=thejoeblowski&size=original",
      "relationship": []
    }
  ],
  "email": "developers@knod.es",
  "edges": {
    "people": {
      "count": 9,
      "rel_types": {
        "twitter-friend": {
          "count": 5
        },
        "twitter-follower": {
          "count": 2
        },
        "facebook-friend": {
          "count": 2
        },
        "follower": {
          "count": 2
        },
        "friend": {
          "count": 7
        }
      }
    },
    "locations": {
      "count": 4,
      "rel_types": {
        "been-to": {
          "count": 2
        },
        "from": {
          "count": 1
        },
        "lives-in": {
          "count": 1
        }
      }
    },
    "documents": {
      "count": 8,
      "rel_types": {
        "author": {
          "count": 8
        }
      }
    }
  },
  "links": [
    {
      "rel": "self",
      "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f345.json"
    },
    {
      "rel": "people",
      "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f345/people.json"
    },
    {
      "rel": "locations",
      "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f345/locations.json"
    },
    {
      "rel": "documents",
      "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f345/documents.json"
    }
  ]
} 

This call in the test harness.

API Docs for this call.

Search People

Knodes provides fast and powerful search of all indexed entities. For people, you can choose to execute a regular search, which matches against names, screen names, etc. Or you can do a relevance search, which finds people who are relevant to the search query, based on prior activity, profile data, etc.

Here is an example of searching Joe Blowski's network for all people relevant to the query "knodes":

https://api.knod.es/people/search.json?customer_id=:CUSTOMER_ID&customer_secret=:CUSTOMER_SECRET&user_id=4fa175ea8c50d85c7c000006&q=knodes&type=relevance

Sample output:

 {
  "total": 8,
  "results": [
    {
      "id": "4fa9a8e8e4b0e1d60db9f390",
      "name": "Quotidian Ventures",
      "photo_url": "http://api.knod.es/media/4fa9b0288e63969d3600017b?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "164086916",
          "screen_name": "qventures",
          "profile_url": "http://twitter.com/qventures",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=qventures&size=original",
          "relationship": [
            "friend"
          ]
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f390.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f347",
      "name": "John Goodwin",
      "photo_url": "http://api.knod.es/media/4f4fcaa18c50d86e31000021?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "facebook",
          "network_id": "1003688",
          "screen_name": "john.goodwin",
          "profile_url": "http://facebook.com/john.goodwin",
          "photo_url": "https://graph.facebook.com/john.goodwin/picture?type=large",
          "relationship": [
            "friend"
          ]
        },
        {
          "network": "twitter",
          "network_id": "15754568",
          "screen_name": "johnnygoods",
          "profile_url": "http://twitter.com/johnnygoods",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=johnnygoods&size=original",
          "relationship": [
            "follower",
            "friend"
          ]
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f347.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f3af",
      "name": "Knodes",
      "photo_url": "http://api.knod.es/media/4f4251c48c50d8743100001b?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "326961285",
          "screen_name": "myknodes",
          "profile_url": "http://twitter.com/myknodes",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=myknodes&size=original",
          "relationship": [
            "friend"
          ]
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f3af.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f346",
      "name": "Ron J. Williams",
      "photo_url": "http://api.knod.es/media/4f4251c48c50d87431000015?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "facebook",
          "network_id": "689301610",
          "screen_name": "ronjwilliams",
          "profile_url": "http://facebook.com/ronjwilliams",
          "photo_url": "https://graph.facebook.com/ronjwilliams/picture?type=large",
          "relationship": [
            "friend"
          ]
        },
        {
          "network": "twitter",
          "network_id": "76613858",
          "screen_name": "ronjdub",
          "profile_url": "http://twitter.com/ronjdub",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=ronjdub&size=original",
          "relationship": [
            "follower",
            "friend"
          ]
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f346.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f39a",
      "name": "Topher Ziobro",
      "photo_url": "http://api.knod.es/media/4f4572318c50d86f31000318?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "20696016",
          "screen_name": "imtopher",
          "profile_url": "http://twitter.com/imtopher",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=imtopher&size=original",
          "relationship": []
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f39a.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f394",
      "name": "Sally Kohn",
      "photo_url": "http://api.knod.es/media/4faab8d98e63969836000009?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "18978610",
          "screen_name": "sallykohn",
          "profile_url": "http://twitter.com/sallykohn",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=sallykohn&size=original",
          "relationship": []
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f394.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f397",
      "name": "Sonal Bains",
      "photo_url": "http://api.knod.es/media/4f63b6888c50d8fe690000ac?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "15906218",
          "screen_name": "sonalbee",
          "profile_url": "http://twitter.com/sonalbee",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=sonalbee&size=original",
          "relationship": []
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f397.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f373",
      "name": "GitHub Jobs",
      "photo_url": "http://api.knod.es/media/4faab8d98e6396983600000a?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "164854390",
          "screen_name": "githubjobs",
          "profile_url": "http://twitter.com/githubjobs",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=githubjobs&size=original",
          "relationship": []
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f373.json"
        }
      ]
    }
  ]
} 

This call in the test harness.

API Docs for this call.

View and Filter Aspects

One of the most powerful features of the Knodes API is the ability to traverse the "uber-graph" we create for your users. Each entity contains an edges attribute:

 {
  "people": {
    "count": 5,
    "rel_types": {
      "twitter-friend": {
        "count": 5
      },
      "twitter-follower": {
        "count": 2
      },
      "facebook-friend": {
        "count": 2
      },
      "follower": {
        "count": 2
      },
      "friend": {
        "count": 5
      }
    }
  },
  "locations": {
    "count": 2,
    "rel_types": {
      "been-to": {
        "count": 2
      },
      "from": {
        "count": 1
      },
      "lives-in": {
        "count": 1
      }
    }
  },
  "documents": {
    "count": 8,
    "rel_types": {
      "author": {
        "count": 8
      }
    }
  }
} 

This object summarizes the outgoing edges, or connections, from that entity. You can dig into each of those sets of connections by simply querying their corresponding "aspects".

People connected to a person

All the people connected to Joe Blowski:

https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f345/people.json?customer_id=:CUSTOMER_ID&customer_secret=:CUSTOMER_SECRET&user_id=4fa175ea8c50d85c7c000006

Sample output:

  {
  "total": 5,
  "results": [
    {
      "id": "4fa9a8e8e4b0e1d60db9f390",
      "name": "Quotidian Ventures",
      "photo_url": "http://api.knod.es/media/4fa9b0288e63969d3600017b?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "164086916",
          "screen_name": "qventures",
          "profile_url": "http://twitter.com/qventures",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=qventures&size=original",
          "relationship": [
            "friend"
          ]
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f390.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f347",
      "name": "John Goodwin",
      "photo_url": "http://api.knod.es/media/4f4fcaa18c50d86e31000021?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "facebook",
          "network_id": "1003688",
          "screen_name": "john.goodwin",
          "profile_url": "http://facebook.com/john.goodwin",
          "photo_url": "https://graph.facebook.com/john.goodwin/picture?type=large",
          "relationship": [
            "friend"
          ]
        },
        {
          "network": "twitter",
          "network_id": "15754568",
          "screen_name": "johnnygoods",
          "profile_url": "http://twitter.com/johnnygoods",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=johnnygoods&size=original",
          "relationship": [
            "follower",
            "friend"
          ]
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f347.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f3af",
      "name": "Knodes",
      "photo_url": "http://api.knod.es/media/4f4251c48c50d8743100001b?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "326961285",
          "screen_name": "myknodes",
          "profile_url": "http://twitter.com/myknodes",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=myknodes&size=original",
          "relationship": [
            "friend"
          ]
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f3af.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f346",
      "name": "Ron J. Williams",
      "photo_url": "http://api.knod.es/media/4f4251c48c50d87431000015?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "facebook",
          "network_id": "689301610",
          "screen_name": "ronjwilliams",
          "profile_url": "http://facebook.com/ronjwilliams",
          "photo_url": "https://graph.facebook.com/ronjwilliams/picture?type=large",
          "relationship": [
            "friend"
          ]
        },
        {
          "network": "twitter",
          "network_id": "76613858",
          "screen_name": "ronjdub",
          "profile_url": "http://twitter.com/ronjdub",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=ronjdub&size=original",
          "relationship": [
            "follower",
            "friend"
          ]
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f346.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f34a",
      "name": "Billy Dee Williams",
      "photo_url": "http://api.knod.es/media/4faa87dd8e63969c36000002?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "230919253",
          "screen_name": "realbdw",
          "profile_url": "http://twitter.com/realbdw",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=realbdw&size=original",
          "relationship": [
            "friend"
          ]
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f34a.json"
        }
      ]
    }
  ]
} 

This call in the test harness.

API Docs for this call.

Locations connected to a person

All the locations connected to Joe Blowski:

https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f345/locations.json?customer_id=:CUSTOMER_ID&customer_secret=:CUSTOMER_SECRET&user_id=4fa175ea8c50d85c7c000006

Sample output:

  {
  "total": 2,
  "results": [
    {
      "id": "fdfa3422-e68f-47a7-9f78-1ab9b543ec31",
      "name": "CHICAGO, IL",
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/locations/fdfa3422-e68f-47a7-9f78-1ab9b543ec31.json"
        }
      ]
    },
    {
      "id": "00ebdcb5-c983-4816-9133-f15e734c0501",
      "name": "NEW YORK, NY",
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/locations/00ebdcb5-c983-4816-9133-f15e734c0501.json"
        }
      ]
    }
  ]
} 

This call in the test harness.

API Docs for this call.

People who live in a location

Now that we've found some locations (we could also have searched for them via /locations/search), let's dig a little deeper. Let's look at all the people in Joe's extended network who live in New York, NY:

https://api.knod.es/locations/00ebdcb5-c983-4816-9133-f15e734c0501/people/lives-in.json?customer_id=:CUSTOMER_ID&customer_secret=:CUSTOMER_SECRET&user_id=4fa175ea8c50d85c7c000006

Sample output:

  {
  "total": 23,
  "results": [
    {
      "id": "4fa9a8e8e4b0e1d60db9f390",
      "name": "Quotidian Ventures",
      "photo_url": "http://api.knod.es/media/4fa9b0288e63969d3600017b?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "164086916",
          "screen_name": "qventures",
          "profile_url": "http://twitter.com/qventures",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=qventures&size=original",
          "relationship": [
            "friend"
          ]
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f390.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f3af",
      "name": "Knodes",
      "photo_url": "http://api.knod.es/media/4f4251c48c50d8743100001b?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "326961285",
          "screen_name": "myknodes",
          "profile_url": "http://twitter.com/myknodes",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=myknodes&size=original",
          "relationship": [
            "friend"
          ]
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f3af.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f346",
      "name": "Ron J. Williams",
      "photo_url": "http://api.knod.es/media/4f4251c48c50d87431000015?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "facebook",
          "network_id": "689301610",
          "screen_name": "ronjwilliams",
          "profile_url": "http://facebook.com/ronjwilliams",
          "photo_url": "https://graph.facebook.com/ronjwilliams/picture?type=large",
          "relationship": [
            "friend"
          ]
        },
        {
          "network": "twitter",
          "network_id": "76613858",
          "screen_name": "ronjdub",
          "profile_url": "http://twitter.com/ronjdub",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=ronjdub&size=original",
          "relationship": [
            "follower",
            "friend"
          ]
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f346.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f38c",
      "name": "OPEN Forum",
      "photo_url": "http://api.knod.es/media/4faac6078e63969b36000004?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "50747187",
          "screen_name": "openforum",
          "profile_url": "http://twitter.com/openforum",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=openforum&size=original",
          "relationship": []
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f38c.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f3ba",
      "name": "SponsorHub",
      "photo_url": "http://api.knod.es/media/4faac6078e63969b36000005?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "358464594",
          "screen_name": "sponsorhub",
          "profile_url": "http://twitter.com/sponsorhub",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=sponsorhub&size=original",
          "relationship": []
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f3ba.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f359",
      "name": "Ann Montgomery",
      "photo_url": "http://api.knod.es/media/4faac6078e63969b36000006?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "36608365",
          "screen_name": "annmontgom",
          "profile_url": "http://twitter.com/annmontgom",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=annmontgom&size=original",
          "relationship": []
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f359.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f39f",
      "name": "Zeb Dropkin ☯",
      "photo_url": "http://api.knod.es/media/4f4fb02e8c50d8e4310000b9?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "782238",
          "screen_name": "zeb",
          "profile_url": "http://twitter.com/zeb",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=zeb&size=original",
          "relationship": []
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f39f.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f36c",
      "name": "Entrepreneur Week",
      "photo_url": "http://api.knod.es/media/4faac6078e63969b36000007?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "73922084",
          "screen_name": "nyew",
          "profile_url": "http://twitter.com/nyew",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=nyew&size=original",
          "relationship": []
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f36c.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f3a8",
      "name": "DueProps",
      "photo_url": "http://api.knod.es/media/4faac6078e63969b36000008?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "317299887",
          "screen_name": "dueprops",
          "profile_url": "http://twitter.com/dueprops",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=dueprops&size=original",
          "relationship": []
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f3a8.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f3b1",
      "name": "Livestream",
      "photo_url": "http://api.knod.es/media/4faac6078e63969b36000009?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "6375322",
          "screen_name": "livestream",
          "profile_url": "http://twitter.com/livestream",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=livestream&size=original",
          "relationship": []
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f3b1.json"
        }
      ]
    }
  ]
} 

This call in the test harness.

API Docs for this call.

User's friends who live in a location

You'll notice the query for people who live in New York, NY returned a lot of results. That's because it picked up every person in Joe's extended network who lives in NYC. Let's make things a little more personal, and filter for just those user's who are friends with Joe:

https://api.knod.es/locations/00ebdcb5-c983-4816-9133-f15e734c0501/people/lives-in.json?customer_id=:CUSTOMER_ID&customer_secret=:CUSTOMER_SECRET&user_id=4fa175ea8c50d85c7c000006&field_relationship=friend

Sample output:

  {
  "total": 3,
  "results": [
    {
      "id": "4fa9a8e8e4b0e1d60db9f390",
      "name": "Quotidian Ventures",
      "photo_url": "http://api.knod.es/media/4fa9b0288e63969d3600017b?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "164086916",
          "screen_name": "qventures",
          "profile_url": "http://twitter.com/qventures",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=qventures&size=original",
          "relationship": [
            "friend"
          ]
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f390.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f3af",
      "name": "Knodes",
      "photo_url": "http://api.knod.es/media/4f4251c48c50d8743100001b?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "326961285",
          "screen_name": "myknodes",
          "profile_url": "http://twitter.com/myknodes",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=myknodes&size=original",
          "relationship": [
            "friend"
          ]
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f3af.json"
        }
      ]
    },
    {
      "id": "4fa9a8e8e4b0e1d60db9f346",
      "name": "Ron J. Williams",
      "photo_url": "http://api.knod.es/media/4f4251c48c50d87431000015?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "facebook",
          "network_id": "689301610",
          "screen_name": "ronjwilliams",
          "profile_url": "http://facebook.com/ronjwilliams",
          "photo_url": "https://graph.facebook.com/ronjwilliams/picture?type=large",
          "relationship": [
            "friend"
          ]
        },
        {
          "network": "twitter",
          "network_id": "76613858",
          "screen_name": "ronjdub",
          "profile_url": "http://twitter.com/ronjdub",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=ronjdub&size=original",
          "relationship": [
            "follower",
            "friend"
          ]
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f346.json"
        }
      ]
    }
  ]
} 

This call in the test harness.

API Docs for this call.

Search Aspects

You can also perform ad hoc queries against any aspect, just as you would for the normal search endpoints.

Search people connected to a person

People conncted to Joe Blowski named "John":

https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f345/people.json?customer_id=:CUSTOMER_ID&customer_secret=:CUSTOMER_SECRET&user_id=4fa175ea8c50d85c7c000006&q=john

Sample output:

  {
  "total": 1,
  "results": [
    {
      "id": "4fa9a8e8e4b0e1d60db9f347",
      "name": "John Goodwin",
      "photo_url": "http://api.knod.es/media/4f4fcaa18c50d86e31000021?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "facebook",
          "network_id": "1003688",
          "screen_name": "john.goodwin",
          "profile_url": "http://facebook.com/john.goodwin",
          "photo_url": "https://graph.facebook.com/john.goodwin/picture?type=large",
          "relationship": [
            "friend"
          ]
        },
        {
          "network": "twitter",
          "network_id": "15754568",
          "screen_name": "johnnygoods",
          "profile_url": "http://twitter.com/johnnygoods",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=johnnygoods&size=original",
          "relationship": [
            "follower",
            "friend"
          ]
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f347.json"
        }
      ]
    }
  ]
} 

This call in the test harness.

API Docs for this call.

People conncted to Joe Blowski relevant to "finance":

https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f345/people.json?customer_id=:CUSTOMER_ID&customer_secret=:CUSTOMER_SECRET&user_id=4fa175ea8c50d85c7c000006&q=finance&type=relevance

Sample output:

  {
  "total": 1,
  "results": [
    {
      "id": "4fa9a8e8e4b0e1d60db9f390",
      "name": "Quotidian Ventures",
      "photo_url": "http://api.knod.es/media/4fa9b0288e63969d3600017b?w=100&h=100&force=1",
      "engagement_score_me_to_them": 0,
      "engagement_score_them_to_me": 0,
      "networks": [
        {
          "network": "twitter",
          "network_id": "164086916",
          "screen_name": "qventures",
          "profile_url": "http://twitter.com/qventures",
          "photo_url": "https://api.twitter.com/1/users/profile_image?screen_name=qventures&size=original",
          "relationship": [
            "friend"
          ]
        }
      ],
      "links": [
        {
          "rel": "self",
          "href": "https://api.knod.es/people/4fa9a8e8e4b0e1d60db9f390.json"
        }
      ]
    }
  ]
} 

This call in the test harness.

API Docs for this call.