/api/v1/assignee/

Upstream view AssigneeList (index assignees, response key assignees). Any field may be null where the bulk data has no value. Default fields (f): assignee_id, assignee_individual_name_first, assignee_individual_name_last, assignee_organization. Default sort (s): [{"assignee_id": "asc"}]. Nested groups usable in q and f with dotted names: assignee_years. When the build in service does not carry this endpoint's data set it answers 501 with X-Status-Reason-Code ERR_NOT_IMPLEMENTED and X-Status-Reason naming the data set.

Routes: GET POST /api/v1/assignee/ GET POST /api/v1/assignee/{pk}/
Response key: assignees
Default f: assignee_id, assignee_individual_name_first, assignee_individual_name_last, assignee_organization
Default s: [{"assignee_id": "asc"}]
Default o: {}
q: required on the list route
Detail key: assignee_id in the path; a "/" in a key is written ":"
Nested groups: assignee_years

Example

curl -s -G -H "X-Api-Key: $KEY" https://patentref.io/api/v1/assignee/ \
  --data-urlencode 'q={"_contains": {"assignee_organization": "Tesla"}}'

import json, os, requests

base_url = "https://patentref.io"
headers = {"X-Api-Key": os.environ["PATENTREF_KEY"]}
params = {"q": {"_contains": {"assignee_organization": "Tesla"}}}
r = requests.get(base_url + "/api/v1/assignee/", headers=headers,
                 params={k: json.dumps(v) for k, v in params.items()})
r.raise_for_status()
data = r.json()
print(data["total_hits"], data["assignees"][:3])

Fields

Kind is how q treats the field (grammar, Field kinds). Sortable fields go in s. Nested fields are named with a dot in q and f; naming the group returns its upstream fields, and a field whose note says it is present only when f names it comes back only then. The rows of a group come in the order of their source (grammar, the response and paging).

Field	Type	Kind	Sortable	Note
`assignee_id`	string	keyword	yes
`assignee_individual_name_first`	string	text with a keyword form	yes
`assignee_individual_name_last`	string	text with a keyword form	yes
`assignee_organization`	string	text with a keyword form	yes
`assignee_type`	string	keyword	yes
`assignee_lastknown_city`	string	text
`assignee_lastknown_state`	string	text
`assignee_lastknown_country`	string	text		An ISO 3166-1 alpha-2 country code in capitals, as PatentsView gives it: the United Kingdom is "GB", and "UK" matches nothing.
`assignee_lastknown_latitude`	number	number	yes
`assignee_lastknown_longitude`	number	number	yes
`assignee_lastknown_location`	string (URL)	keyword		Link to the detail record: https://patentref.io/api/v1/location/<id>/, with a "/" in the id written ":"; null when the id is null. Kind: keyword: in q this name matches the id behind the link (for example "H01" for cpc_current.cpc_class), not the URL.
`assignee_first_seen_date`	string	date	yes
`assignee_last_seen_date`	string	date	yes
`assignee_num_inventors`	number	number	yes
`assignee_num_patents`	number	number	yes
`assignee_years_active`	number	number	yes
`assignee_years`	group (list of objects)			Nested group: name it in f ("assignee_years") for every field of the group, or "assignee_years.<field>" for one; query its fields in q with the same dotted names.
`assignee_years.year`	integer	number
`assignee_years.num_patents`	integer	number
`raw_assignee_individual_name_first`	string	returned when f names it		PatentRef addition: the first name as printed on the grant of the assignee's most recent patent, the patent its other names come from (PatentsView g_assignee_not_disambiguated), beside the disambiguated name, which is PatentsView's one label for a whole cluster of names. Present only when f names it (raw_assignee_individual_name_first), then on every record; null where the bulk data has none or the data in service predates it. Kind: f-only. Returned when f names it; q or s on it answers 400 ERR_Q.
`raw_assignee_individual_name_last`	string	returned when f names it		PatentRef addition: the last name as printed on the grant of the assignee's most recent patent, the patent its other names come from (PatentsView g_assignee_not_disambiguated), beside the disambiguated name, which is PatentsView's one label for a whole cluster of names. Present only when f names it (raw_assignee_individual_name_last), then on every record; null where the bulk data has none or the data in service predates it. Kind: f-only. Returned when f names it; q or s on it answers 400 ERR_Q.
`raw_assignee_organization`	string	returned when f names it		PatentRef addition: the organization's name as printed on the grant of the assignee's most recent patent, the patent its other names come from (PatentsView g_assignee_not_disambiguated), beside the disambiguated name, which is PatentsView's one label for a whole cluster of names. Present only when f names it (raw_assignee_organization), then on every record; null where the bulk data has none or the data in service predates it. Kind: f-only. Returned when f names it; q or s on it answers 400 ERR_Q.

Machine-readable: this page's data as JSON, and the operation in openapi.json (operationId AssigneeList).