How to query the FOAF social graph using our API

REST-URL

https://www.foaf-search.net/api/rest?access_key=<your-access-key>&method=<method-name> (+ method parameters and arguments)

All results are returned in JSON (JavaScript Object Notation) format.

If an error occurs the result is an object with the property 'error':

{"error": "<error message>"}
The API uses an integer ID to identify things. Things can be everything with a foaf:name or a foaf:nick and are usually agents (persons, groups, organisations) or places. The URI identifying a thing corresponding to our ID is
https://www.foaf-search.net/thing/<id>
We do not make use of this yet. It's just in case you need an URI instead of an integer and redirects to the profile page of the thing, which always has the URL
https://www.foaf-search.net/Profile?personid=<id>
The parameter is called "personid" instead of "id" or "thingid" in the URL for historical reasons.

As a thing/agent can have many different URIs, OpenIDs and mailboxes, we keep a list of identifiers. This list (including all names and nicks) can be retrieved with the API method get_thing_data.

Searching for things

Getting information about a thing

Getting provenance information

Searching for things

Method: search

Description:

Returns the search result for the given query.

Parameters:

query: The name, e-mail, nick, homepage, openid, mbox-hash or URI to search for.

Example: https://www.foaf-search.net/api/rest?access_key=<access-key>&method=search&query=timbl

{"has_more": false,
 "results":
  [ {"id": 1,
     "link_text": "Sir Tim Berners-Lee aka Timothy Berners-Lee (http://identi.ca/user/45563)",
     "views": 1485},
    {"id": 1745879,
     "link_text": "Tim Berners-Lee (http://semantictweet.com/timbl#me)",
     "views": 4}
  ]
}
has_more = true indicates that more results can be found but are not returned due to resource constraints.

Method: get_rdf_type

Description:

Returns up to 100 things of a given class.

Parameters:

rdftype: the class URI
start (optional): the nr of the first result (defaults to 0 if end is not given)
end (optional): return first 100 results with a nr < end (if start is not given)

Example: https://www.foaf-search.net/api/rest?access_key=<access-key>&method=get_rdf_type&rdftype=http%3A//semantic-mediawiki.org/swivt/1.0%23Subject

{"has_more": true,
 "results":
  [{"id": 1,
    "nr": 0,
    "link_text": "Sir Tim Berners-Lee aka Timothy Berners-Lee (http://identi.ca/user/45563)"},
   ...
  ]
}    

Method: get_interest

Description:

Returns up to 100 agents with a given foaf:interest.

Parameters:

interest: the foaf:interest URI
start (optional): the nr of the first result (defaults to 0 if end is not given)
end (optional): return first 100 results with a nr < end (if start is not given)

Example: https://www.foaf-search.net/api/rest?access_key=<access-key>&method=get_interest&interest=http%3A//www.w3.org/2001/sw/

{"has_more": false,
 "results":
  [ {"id": 4169,
     "nr": 0,
     "link_text": "Daniel Krech (http://identi.ca/user/12744)"},
    ...
  ]
}

Method: get_things_near

Description:

Returns things near the given coordinates. The search radius varies from 10km to 100km depending on the concentration of coordinates. The maximum number of results is 500.

Parameters:

latitude: the latitude
longitude: the longitude
mapmode (optional): search only for agents or places or both ('agents' or 'places', defaults to 'both')

Example: https://www.foaf-search.net/api/rest?access_key=<access-key>&method=get_things_near&latitude=13.0&longitude=13.2

[ {"distance": "40.8 km",
   "dist": 40792.944812748989,
   "long": 13.5666666666667,
   "linktext": "Kukawa",
   "lat": 12.9166666666667,
   "id": 60136},
  {"distance": "74.5 km",
   "dist": 74468.366472280512,
   "long": 13.133333333333301,
   "linktext": "Toumour",
   "lat": 13.6666666666667, "id": 58698},
  {"distance": "74.6 km",
   "dist": 74631.647506532841,
   "long": 12.6267,
   "linktext": "Diffa Airport",
   "lat": 13.3729,
   "id": 155589},
  ...
]

Getting information about a thing

Method: get_thing_data

Description:

Returns a list of properties of a given thing.
Possible properties are: mbox, mbox_sha1sum, uri, openid, weblog, name, nick, bestname and bestnick

Parameters:

id: the id of the thing

Example: https://www.foaf-search.net/api/rest?access_key=<access-key>&method=get_thing_data&id=1

[{"property": "mbox", "value": "mailto:timbl@w3.org"},
 {"property": "mbox_sha1sum", "value": "37ae6b3bfd05813b4299085aa7b1fa4560081e9f"},
 {"property": "mbox_sha1sum", "value": "6505cb7ac99c3e8b7cbe99a044cbe1c5d1faef21"},
 {"property": "mbox_sha1sum", "value": "965c47c5a70db7407210cef6e4e6f5374a525c5c"},
 {"property": "name", "value": "Sir Tim Berners-Lee"},
 {"property": "name", "value": "Tim Berners-Lee"},
 {"property": "name", "value": "Timothy Berners-Lee"},
 {"property": "nick", "value": "TimBL"},
 {"property": "openid", "value": "http://www.w3.org/People/Berners-Lee/"},
 {"property": "weblog", "value": "http://my.opera.com/timbl/"},
 {"property": "weblog", "value": "http://www.w3.org/People/Berners-Lee"},
 {"property": "weblog", "value": "http://www.w3.org/People/Berners-Lee/"},
 {"property": "uri", "value": "http://advogato.org/person/timbl/foaf.rdf#me"},
 {"property": "uri", "value": "http://berrueta.net/personal/people#timbl"},
 {"property": "uri", "value": "http://dbpedia.org/resource/Tim_Berners-Lee"},
 {"property": "uri", "value": "http://identi.ca/user/45563"},
 {"property": "uri", "value": "http://infomesh.net/2003/people#TimBL"},
 {"property": "uri", "value": "http://my.opera.com/timbl/xml/foaf#me"},
 {"property": "uri", "value": "http://norman.walsh.name/knows/who#tim-berners-lee"},
 {"property": "uri", "value": "http://norman.walsh.name/knows/who/tim-berners-lee"},
 {"property": "uri", "value": "http://rdf.freebase.com/ns/guid.9202a8c04000641f800000000003b0aa"},
 {"property": "uri", "value": "http://semanticweb.org/id/Tim_Berners-2DLee"},
 {"property": "uri", "value": "http://semanticweb.org/id/Tim_Berners-Lee"},
 {"property": "uri", "value": "http://www.advogato.org/person/timbl/foaf.rdf#me"},
 {"property": "uri", "value": "http://www.w3.org/People/Berners-Lee/card#i"},
 {"property": "uri", "value": "http://www4.wiwiss.fu-berlin.de/bookmashup/persons/Tim+Berners-Lee"},
 {"property": "uri", "value": "http://www4.wiwiss.fu-berlin.de/dblp/resource/person/100007"}
]

Method: get_related (premium access only)

Description:

Returns a limited list of related agents.

Parameters:

id: the id of the agent
relation: the type of the relation: 'knows' or 'memberOf'
reverse (optional): return the inverse relation ('true' or 'false', defaults to 'false')

Example: https://www.foaf-search.net/api/rest?access_key=<access-key>&method=get_related&id=1&relation=knows

{"has_more": true,
 "results":
  [ {"link_text": "Aaron Swartz", "id": 4193},
    {"link_text": "Amy van der Hiel", "id": 4203},
    ...
  ]
}

Method: get_more_related (premium access only)

Description:

Returns an unlimited list of related agents.

Parameters:

id: the id of the agent
relation: the type of the relation: 'knows' or 'memberOf'
reverse (optional): return the inverse relation ('true' or 'false', defaults to 'false')

Example: https://www.foaf-search.net/api/rest?access_key=<access-key>&method=get_more_related&id=1&relation=knows

[{"link_text": "Aaron Swartz", "id": 4193},
 {"link_text": "Amy van der Hiel", "id": 4203},
 ...
]

Method: get_based_near (premium access only)

Description:

Returns coordinates provided with the foaf:based_near property. If the coordinates are those of another thing, the id and link text of that thing is also returned.

Parameters:

id: the id of the thing

Example: https://www.foaf-search.net/api/rest?access_key=<access-key>&method=get_based_near&id=1

[{"latitude": "42.361860",
  "longitude": "-71.091840"},
 {"latitude": "38.8951118",
  "longitude": "-77.0363658",
  "nearid": 2832288,
  "link_text": "Washington, Washington, D.C., United States aka Washington"
 }
 ...
]

Method: get_nearest_airport (premium access only)

Description:

Returns coordinates provided with the contact:nearestAirport property. If the coordinates are those of another thing, the id and link text of that thing is also returned.

Parameters:

id: the id of the thing

Example: https://www.foaf-search.net/api/rest?access_key=<access-key>&method=get_nearest_airport&id=1

[{"latitude": "42.366666666667",
  "longitude": "-71",
  "nearid": 27171,
  "link_text": "Logan International"
 },
 ...
]

Method: get_profile_triples (premium access only)

Description:

Returns triples for the given thing as a SPARQL result set.

Parameters:

id: the id of the thing

Example: https://www.foaf-search.net/api/rest?access_key=<access-key>&method=get_profile_triples&id=1

{"head":
  {"vars": ["subj", "pred", "obj"]},
 "results":
  {"bindings":
    [ {"subj": {"type": "uri", "value": "http://www.w3.org/People/Berners-Lee/card#i"},
       "pred": {"type": "uri", "value": "http://xmlns.com/foaf/0.1/knows"},
       "obj": {"type": "uri", "value": "http://eikeon.com/foaf.rdf#eikeon"}
      }, 
      ...
    ]
  }
}

Getting provenance information

Method: get_profile_quads (premium access only)

Description:

Returns quads for the given thing as a SPARQL result set.

Parameters:

id: the id of the thing

Example: https://www.foaf-search.net/api/rest?access_key=<access-key>&method=get_profile_quads&id=1

{"head":
  {"vars": ["graph", "subj", "pred", "obj"]},
 "results":
  {"bindings":
    [ {"graph": {"type": "uri", "value": "http://www.w3.org/People/Berners-Lee/card.rdf"},
       "subj": {"type": "uri", "value": "http://www.w3.org/People/Berners-Lee/card#i"},
       "pred": {"type": "uri", "value": "http://xmlns.com/foaf/0.1/knows"},
       "obj": {"type": "uri", "value": "http://id.ecs.soton.ac.uk/person/1650"}}
      },
      ...
    ]
  }
}

Method: source (premium access only)

Description:

Returns the list of source documents for a given property of a given thing.

Parameters:

id: the id of the thing
value: the value of the property
prop: the property

Example: https://www.foaf-search.net/api/rest?access_key=<access-key>&method=source&id=1&prop=http%3A%2F%2Fxmlns.com%2Ffoaf%2F0.1%2Fhomepage&value=http%3A%2F%2Fmy.opera.com%2Ftimbl%2F

["http://my.opera.com/chaals/xml/foaf/",
 "http://my.opera.com/chaals/xml/foaf",
 ...
]

Method: source_related (premium access only)

Description:

Returns the list of source documents for a given relation between two things.

Parameters:

id1: the id of the first thing
id2: the id of the second thing
relation: the type of the relation: 'knows' or 'memberOf'

Example: https://www.foaf-search.net/api/rest?access_key=<access-key>&method=source_related&id1=1&id2=4203&relation=knows

["http://www.w3.org/People/Berners-Lee/card.rdf",
 "http://dig.csail.mit.edu/2008/webdav/timbl/foaf.rdf",
 ...
]

Method: source_coords (premium access only)

Description:

Returns the list of source documents for a given thing and coordinates.

Parameters:

id: the id of the thing
pred: the type of the coordinate: 'contact:nearestAirport' or 'foaf:based_near'
latitude: the latitude
longitude: the longitude

Example: https://www.foaf-search.net/api/rest?access_key=<access-key>&method=source_coords&id=1&pred=foaf:based_near&longitude=-71.091840;&latitude=42.361860

["http://www.w3.org/People/Berners-Lee/card.rdf",
 "http://dig.csail.mit.edu/2008/webdav/timbl/foaf.rdf",
 ...
]

(c) 2018 netEstate GmbH • Imprint/Privacy