UCSF Profiles JSON API

What You Need to Know

Summary

  • Use this API to show UCSF researchers' publications, photos, narrative and other information from UCSF Profiles in your websiteapp or app
  • Data is encoded in JSON format, perfect for use in a wide variety of applications (includes CORS and JSONP support)
  • And we offer free support!
Conditions of use
  • Contact us to tell us you're using our APIs — so we don't break your app by mistake when we make updates
  • Add an acknowledgement — we have HTML samples to copy/paste from
  • If you're caching results, refresh at least weekly to prevent outdated data

Two Minute Quick Start

you need to be on the UCSF network or VPN to see this

See an interactive working example:

Click on these examples of API output: What's going on here?
  • API calls are GET requests to URL https://api.profiles.ucsf.edu/json/v2/ which returns JSON
  • You can specify the person you want using a variety of UCSF people identifiers (see below)
  • You need to tell us who's making the request. If the data will be shown on example.ucsf.edu, specify "source=example.ucsf.edu"

How to Specify A User

  1. Profiles URL Name
    Given a URL like profiles.ucsf.edu/alexandra.brown, specify ProfilesURLName=alexandra.brown
  2. EPPN
    Given an EPPN like [email protected], specify EPPN=[email protected]
  3. URL
    Given a URL like "https://profiles.ucsf.edu/tung.nguyen", specify URL=https://profiles.ucsf.edu/tung.nguyen
    (A variety of legacy UCSF Profiles URLs are also supported.)
  4. Employee ID (strongly discouraged)
    Have a 9-digit employee ID? You can specify EmployeeID=123456789  —  but we strongly recommend you use EPPNs instead. Email us. It's easy. We'll show you how.
  5. Profiles Node ID (deprecated)
    Have a Profiles node ID, the internal identifier Profiles uses after Feb 2013? Specify ProfilesNodeID=370974
    Profiles used one series NodeIDs from Feb 2013–May 2018, and then every NodeID changed in May 2018. We will attempt to transparently map legacy (2013-2018) nodeIDs to current ones, but can't guarantee that it will work.
  6. Profiles Person ID (deprecated)
    Have a user's Profile Person ID, the number that was part of Profiles URLs before Feb 2013? (example: profiles.ucsf.edu/ProfileDetails.aspx?Person=5036574) Specify Person=5036574
    Hint: We have a lookup tool to find old school Profiles Person IDs
  7. FNO Code (deprecated)
    ​FNO codes look deceptively like email addresses—but they're not! These are rarely used, and we support only those FNOs that were issued before April 2018. Given FNO code "[email protected]", specify FNO=[email protected]

Two API details you should know

  1. Request Source (required)
    Let us know which app or website is using the API, e.g. source=example.ucsf.edu or source=UCSF+Mobile+App+for+iOS
  2. Using JavaScript?
    If you're developing a JavaScript application, we support CORS, so anyone can make XMLHttpRequests requests to our content. (Older apps can use JSONP; just specify callback=your_function_name_here.)

Details

  • How to detect an error
    In case of error, the JSON will include an error description like { "error" : "Human-readable error message here" } — check for the existence of this string
    We return a 404 code if we can't find a user
    We return a 400 code if you send an invalid request
  • Content-Type
    The API will return JSON content in content-type application/json, and answer JSONP requests as text/javascript.
  • Accessing data for multiple profiles at once
    If you want information about a large number of users at once, please wait at least 1 second between subsequent HTTP calls.

Support