Locations Endpoint

GET /api/locations/query?q{,f,o,s}
POST /api/locations/query

This will search for locations matching the query string (q) and returning the data fields listed in the field string (f) sorted by the fields in the sort string (s) using options provided in the option string (o).

The HTTP GET request method is the preferred access mechanism; however when the query parameters exceed a reasonable size (around 2,000 characters), then the POST method can be used. When using the POST method, the query parameters should be embedded within a JSON string within the request body.

Name Description Details
q JSON formatted object containing the query parameters. See below for details on formatting this object. string, required
example: {"location_city":"Mount Airy"}
f JSON formatted array of fields to include in the results. If not provided, defaults to location_id, location_city, location_state, and location_country . string, optional
example: ["location_id", "location_city","location_state"]
s JSON formatted array of objects to sort the results. If not provided, defaults to location_key_id . string, optional
example: [{"location_total_num_inventors":"desc"}]
o

JSON formatted object of options to modify the query or results. Available options are:

matched_subentities_only — Only subentity data that matches the subentity specific criteria is included in results. Defaults to true.

include_subentity_total_counts — Total counts of unique subentities included in results. Defaults to false.

page — return only the Nth page of results. Defaults to 1.

per_page — Size of each page of results. Defaults to 25.

string, optional
example: o={"matched_subentities_only": "true", "page": 2, "per_page": 50, "include_subentity_total_counts": "false"}
format

Specifies the response data format. If not provided, defaults to JSON. Available options are:

json

xml

string, optional
example: format=xml

An example of a complete API call using the GET verb is:

http://www.patentsview.org/api/locations/query?q={"location_city":"Mount Airy"}&f=["location_id","location_state","location_total_num_patents"]

An example of the equivalent API call using the POST verb is:

http://www.patentsview.org/api/locations/query

with the body containing:

{"q":{"location_city":"Mount Airy"},"f":["location_id", "location_state","location_total_num_patents"]}

Examples

Location Field List

API Field Name Group Common Name Type Query Description
appcit_app_number application_citations Application Number string Y Application ID (issued by USPTO) for application cited by the selected patent
appcit_category application_citations Category string Y Entity that cited an application in the selected patent
appcit_date application_citations Filing Date date Y Filing date for application cited in the selected patent
appcit_kind application_citations Kind string Y Patent kind of application cited by patent
appcit_sequence application_citations Sequence integer N Order in which a citation is cited by patent
app_country applications Country string Y Country in which patent application was filed, always U.S.
app_date applications Filing Date date Y Date the patent application was filed (filing date)
app_number applications Number string Y Application ID assigned by USPTO
app_type applications Type string Y Patent Application Type (From XML data dictionary). 02 through 28 = Utility application; 29, D = Design application; 60 = Provisional application; 90 = Reexamination request
assignee_first_name assignees First Name string Y First name, if assignee is individual
assignee_first_seen_date assignees First Seen Date date Y Earliest patent grant date for all of an asisgnee's patents in the database
assignee_id assignees ID string Y Unique database assignee ID assigned by disambiguation algorithm
assignee_last_name assignees Last Name string Y Last name, if assignee is individual
assignee_last_seen_date assignees Last Seen Date date Y Most recent patent grant date for all of the asisgnee's patents in the database
assignee_lastknown_city assignees Last Known City string Y Assignee's country as of their most recent patent grant date (equivalently, as of assignee_last_seen_date)
assignee_lastknown_country assignees Last Known Country string Y Assignee's city as of their most recent patent grant date (equivalently, as of assignee_last_seen_date)
assignee_lastknown_latitude assignees Last Known Latitude float N Latitude for assignee's location as of their most recent patent grant date (equivalently, as of assignee_last_seen_date)
assignee_lastknown_location_id assignees Last Known Location ID string Y Unique database ID for the assignee's location on their most recent patent grant date (equivalently, as of assignee_last_seen_date)
assignee_lastknown_longitude assignees Last Known Longitude float N Longitude for assignee's location as of their most recent patent grant date (equivalently, as of assignee_last_seen_date)
assignee_lastknown_state assignees Last Known State string Y Assignee's state as of their most recent patent grant date (equivalently, as of assignee_last_seen_date)
assignee_num_patents_for_location assignees Number of Patents for Location integer N Number of patents in the database for a given assignee and location
assignee_organization assignees Organization string Y Organization name, if assignee is organization
assignee_total_num_inventors assignees Total Number of Inventors integer Y Total number of inventors in database for a given assignee (as indicated by unique assignee_id)
assignee_total_num_patents assignees Total Number of Patents integer Y Total number of patents in database for a given assignee (as indicated by unique assignee_id)
assignee_type assignees Type string Y Classification of assignee. 2 - US Company or Corporation, 3 - Foreign Company or Corporation, 4 - US Individual, 5 - Foreign Individual, 6 - US Government, 7 - Foreign Government, 8 - Country Government, 9 - State Government (US). Note: A "1" appearing before any of these codes signifies part interest
cited_patent_category cited_patents Patent Category string Y Category of cited patent
cited_patent_date cited_patents Patent Date date Y Grant data of cited patent
cited_patent_kind cited_patents Patent Kind string Y Patent kind of cited patent (see patent_kind for details)
cited_patent_number cited_patents Patent Number string Y Patent number of cited patent
cited_patent_sequence cited_patents Patent Sequence string N Order in which patent is cited by the selected patent
cited_patent_title cited_patents Patent Title string Y Title of cited patent
citedby_patent_category citedby_patents Patent Category string Y Category of citing patent
citedby_patent_date citedby_patents Patent Date date Y Grant date of patent citing the selected patent
citedby_patent_kind citedby_patents Patent Kind string Y Patent kind of citing patent (see patent_kind for details)
citedby_patent_number citedby_patents Patent Number string Y Patent number of citing patent
citedby_patent_title citedby_patents Patent Title string Y Title of citing patent
cpc_category cpcs Category string Y Top Level Cooperative Patent Classification (CPC) category (http://www.cooperativepatentclassification.org/index.html)
cpc_first_seen_date cpcs First Seen Date date Y Grant date of the earliest patent in the database within a CPC subsection.
cpc_group_id cpcs Group ID string Y CPC group ID
cpc_group_title cpcs Group Title string Y Description of CPC group
cpc_last_seen_date cpcs Last Seen Date date Y Grant date of the most recent patent in the database within a CPC subsection
cpc_num_patents_for_location cpcs Number of Patents for Location integer N Number of patents for a location within a CPC subsection
cpc_section_id cpcs Section ID string Y CPC section ID (A = Human Necessitites, B = Performing Operations; Transporint, C = Chemistry; Metallurgy, D = Textiles; paper, E = Fixed Constructing, F = Mechanical Engineering; Lighting; Heating; Weapons; Blasting Engines; Pumps, G = Physics, H = Electricity, Y = General Tagging of new technological developments)
cpc_sequence cpcs Sequence integer Y Order of the CPC classification in the list of classifications for the selected patent
cpc_subgroup_id cpcs Subgroup ID string Y CPC subgroup ID
cpc_subgroup_title cpcs Subgroup Title string Y Description of CPC subgroup
cpc_subsection_id cpcs Subsection ID string Y CPC subsection ID
cpc_subsection_title cpcs Subsection Title string Y Description of CPC subsection
cpc_total_num_assignees cpcs Total Number of Assignees integer Y Total number of unique assignees on patents within a CPC subsection
cpc_total_num_inventors cpcs Total Number of Inventors integer Y Total number of unique inventors on patents within a CPC subsection
cpc_total_num_patents cpcs Total Number of Patents integer Y Total number of patents within a CPC subsection
govint_contract_award_number gov_interests Contract/Award Number string Y Contract or award number as reported in the government interest statement on patents (if available)
govint_org_id gov_interests Organization ID integer Y Organization ID of the U.S. government agency reported in the government interest statement on patents (if available)
govint_org_level_one gov_interests Top Level Government Organization string Y The top-level U.S. government organization name related to the organization reported in the government interest statement on patents (if available). For example, the National Institutes of Health report to the U.S. Department of Health and Human Services.
govint_org_level_two gov_interests Second Level Government Organization string Y The second-level U.S. government organization name related to the organization reported in the government interest statement on patents (if available). For example, the National Institutes of Health is second-level in relation to the National Heart, Lung, and Blood Institute.
govint_org_level_three gov_interests Third Level Government Organization string Y The third-level U.S. government organization name related to the organization reported in the government interest statement on patents (if available). For example, the National Institute for Occupational Safety and Health is third-level in relation to the Centers for Disease Control and Prevention that report to the U.S. Department of Health and Human Services.
govint_org_name gov_interests Organization Name string Y Name of the U.S. government organization reported in the government interest statement on patents (if available).
govint_raw_statement gov_interests Government Interest Statement full text Y The full government interest statement as reported on a given patent (if available).
inventor_first_name inventors First Name string Y First name of inventor
inventor_first_seen_date inventors First Seen Date date Y Earliest patent grant date for all the inventor's patents in the database
inventor_id inventors ID string Y Unique database inventor ID by disambiguation algorithm
inventor_last_name inventors Last Name string Y Last name of inventor
inventor_last_seen_date inventors Last Seen Date date Y Most recent patent grant date for all the inventor's patents in the database
inventor_lastknown_city inventors Last Known City string Y Inventor's city as of their most recent patent grant date (equivalently, as of inventor_last_seen_date)
inventor_lastknown_country inventors Last Known Country string Y Inventor's country as of their most recent patent grant date (equivalently, as of inventor_last_seen_date)
inventor_lastknown_latitude inventors Last Known Latitude float N Latitude of inventor's city as of their most recent patent grant date (equivalently, as of inventor_last_seen_date)
inventor_lastknown_location_id inventors Last Known Location ID string Y Unique database ID for the inventor's location as of their most recent patent grant date (equivalently, as of inventor_last_seen_date)
inventor_lastknown_longitude inventors Last Known Longitude float N Longitude of inventor's city as of their most recent patent grant date (equivalently, as of inventor_last_seen_date)
inventor_lastknown_state inventors Last Known State string Y Inventor's state as of their most recent patent grant date (equivalently, as of inventor_last_seen_date)
inventor_num_patents_for_location inventors Number of Patents for Location integer N Number of patents for an inventor within a location
inventor_total_num_patents inventors Total Number of Patents integer Y Total number of patents in the database for a given inventor (as indicated by unique inventor_id)
ipc_action_date ipcs Action Date date N Date an International Patent Classification (IPC) is issued for the patent
ipc_class ipcs Class string Y Second hierarchial level of the IPC system, sections are subdivided into classes
ipc_classification_data_source ipcs Classification Data Source string N “H” defining “Human - Generated”, “M” defining “Machine - Generated” and “G” defining “G enerated via Software”
ipc_classification_value ipcs Classification Value string Y “ I ” defining “invention information” or “N” defining “non - invention information”
ipc_first_seen_date ipcs First Seen Date date Y Grant date of the earliest patent in the database within a IPC group
ipc_last_seen_date ipcs Last Seen Date date Y Grant date of the most recent patent in the database within a IPC group
ipc_main_group ipcs Main Group string Y Subdivisions of the IPC subclass
ipc_section ipcs Section string Y Highest hierarchical levels of the IPC corresponding to broad technical fields ( A = Human Necessitites, B = Performing Operations; Transporint, C = Chemistry; Metallurgy, D = Textiles; paper, E = Fixed Constructing, F = Mechanical Engineering; Lighting; Heating; Weapons; Blasting Engines; Pumps, G = Physics, H = Electricity)
ipc_sequence ipcs Sequence integer Y Order of the IPC classification in the list of classifications for the selected patent
ipc_subclass ipcs Subclass string Y Subdivisions IPC class
ipc_subgroup ipcs Subgroup string Y Subdivisions of IPC main group
ipc_symbol_position ipcs Position string Y First or later position of symbols. The position of the first invention information classification can be recognized by this field. The letters "F" and "L" are used for the first and later position, respectively.
ipc_total_num_assignees ipcs Total Number of Assignees integer Y Total number of unique assignees on patents within an IPC class
ipc_total_num_inventors ipcs Total Number of Inventors integer Y Total number of unique inventors on patents within an IPC class
ipc_version_indicator ipcs Version Indicator date N The version of the IPC classification system
location_city locations City string Y City associated with a location_id
location_country locations Country string Y Country associated with a location_id
location_id locations Location ID string Y Unique location ID generated by the disambiguation algorithm
location_key_id locations Location key id string N Special identifier used as the default sort field for the location query. This field may be deprecated in a future version.
location_latitude locations Latitude float N Latitude associated with a location_id
location_longitude locations Longitude float N Longitude associated with a location_id
location_state locations State string Y State assocaited with a location_id
location_total_num_assignees locations Total Number of Assignees integer Y Number of unique assignees on patents for a given location
location_total_num_inventors locations Total Number of Inventors integer Y Number of unique inventors on patents for a given location
location_total_num_patents locations Total Number of Patents integer Y Number of patents for the selected location
nber_category_id nbers Category ID string Y National Bureau of Economic Research (NBER) technology category ID (see nber_category_title for details)
nber_category_title nbers Category Title string Y Description of NBER category
nber_first_seen_date nbers First Seen Date date Y Grant date of the earliest patent in the database within a NBER subcategory
nber_last_seen_date nbers Last Seen Date date Y Grant date of the most recent patent in the database within a NBER subcategory
nber_num_patents_for_location nbers Number of Patents for NBER Subcategory integer Y Number of patents within a NBER subcategory for a given inventor
nber_subcategory_id nbers Subcategory ID string Y NBER subcategory ID (see nber_subcategory_title for details)
nber_subcategory_title nbers Subcategory Title string Y Description of NBER subcategory
nber_total_num_assignees nbers Total Number of Assignees integer Y Total number of unique assignees on patents within a NBER subcategory
nber_total_num_inventors nbers Total Number of Inventors integer Y Total number of unique inventors on patents within a NBER subcategory
nber_total_num_patents nbers Total Number of Patents integer Y Total number of patents within a NBER subcategory
patent_abstract patents Abstract full text N Abstract of the patent
patent_average_processing_time patents Average Processing Time integer Y Average processing time for patents in the same USPC mainclass category as the selected patent
patent_date patents Grant Date date Y Date patent was granted
patent_firstnamed_assignee_city patents First Named Assignee City string Y City of the location of the first-named (i.e. first in the list) assignee on the patent
patent_firstnamed_assignee_country patents First Named Assignee Country string Y Country of the location of the first-named (i.e. first in the list) assignee on the patent
patent_firstnamed_assignee_id patents First Named Assignee ID string Y Assignee ID (assignee_id) for the first-named (i.e. first in the list) assignee on the patent
patent_firstnamed_assignee_latitude patents First Named Assignee Latitude float N Latitude of the location of the first-named (i.e. first in the list) assignee on the patent
patent_firstnamed_assignee_location_id patents First Named Assignee Location ID string Y Unique database ID for the location of the first-named (i.e. first in the list) assignee on the patent
patent_firstnamed_assignee_longitude patents First Named Assignee Longitude float N Longitude of the location of the first-named (i.e. first in the list) assignee on the patent
patent_firstnamed_assignee_state patents First Named Assignee State string Y State of the location of the the first-named (i.e. first in the list) assignee on the patent
patent_firstnamed_inventor_city patents First Named Inventor City string Y City of the location of the the first-named (i.e. first in the list) inventor on the patent
patent_firstnamed_inventor_country patents First Named Inventor Country string Y Country of the location of the first-named (i.e. first in the list) inventor on the patent
patent_firstnamed_inventor_id patents First Named Inventor ID string Y Inventor ID (inventor_id) for the first-named (i.e. first in the list) inventor on the patent
patent_firstnamed_inventor_latitude patents First Named Inventor Latitude float N Latitude of the location of the first-named (i.e. first in the list) inventor on the patent
patent_firstnamed_inventor_location_id patents First Named Inventor Location ID string Y Unique database ID for the location of the first-named (i.e. first in the list) inventor on the patent
patent_firstnamed_inventor_longitude patents First Named Inventor Longitude float N Longitude of the location of the first-named (i.e. first in the list) inventor on the patent
patent_firstnamed_inventor_state patents First Named Inventor State string Y State of the location of the first-named (i.e. first in the list) inventor on the patent
patent_kind patents Kind string Y World Intellectual Property Organization (WIPO) Standard ST.16 Patent Code (http://www.uspto.gov/learning-and-resources/support-centers/electronic-business-center/kind-codes-included-uspto-patent)
patent_num_cited_by_us_patents patents Number Cited by US Patents integer Y Number of times the patent was cited by other US patents
patent_num_cited_by_us_patents_for_location patents Number Cited by US Patents for Location integer N Number of times a patent was cited by other US patents for a selected location
patent_num_claims patents Number of Claims integer N Number of claim statements on the patent
patent_num_combined_citations patents Number of Combined Citations integer Y Number of patents and applications cited by the selected patent. This is the sum of citations of US patents, foreign patents, and US applications
patent_num_foreign_citations patents Number of Foreign Citations integer Y Number of foreign patents cited by the selected patent
patent_num_us_application_citations patents Number of US Application Citations integer Y Number of US applications cited by the selected patent
patent_num_us_patent_citations patents Number of US Patent Citations integer Y Number of US patents cited by the selected patent
patent_number patents Number string Y US Patent number, as assigned by USPTO
patent_processing_time patents Processing Time integer Y Time from filing application date to grant date for the patent
patent_title patents Title full text Y Title of the patent
patent_type patents Type string Y Category of patent. There are 6 possible type: "Defensive Publication" - 509, "Design" - 474736, "Plant" - 21052, "Reissue" - 16416, "Statutory Invention Registration" - 2254, "Utility" - 4910906.
patent_year patents Year integer Y Year patent was granted
rawinventor_first_name rawinventors First Name string Y Inventor first name before disambiguation as listed on the selected patent
rawinventor_last_name rawinventors Last Name string Y Inventor last name before disambiguation as listed on the selected patent
uspc_first_seen_date uspcs First Seen Date date Y Grant date of the earliest patent in the database within a USPC mainclass
uspc_last_seen_date uspcs Last Seen Date date Y Grant date of the most recent patent in the database within a USPC mainclass
uspc_mainclass_id uspcs Mainclass ID string Y ID of the USPC mainclass
uspc_mainclass_title uspcs Mainclass Title string Y Description of USPC mainclass
uspc_num_patents_for_location uspcs Number of Patents for Location integer N Number of patents within a USPC mainclass for a given location
uspc_sequence uspcs Sequence integer Y Order of the USPC classification in the list of classifications for the selected patent
uspc_subclass_id uspcs Subclass ID string Y ID of USPC subclass
uspc_subclass_title uspcs Subclass Title string Y Description of USPC subclass
uspc_total_num_assignees uspcs Total Number of Assignees integer Y Total number of unique assignees on patents within a USPC mainclass
uspc_total_num_inventors uspcs Total Number of Inventors integer Y Total number of unique inventors on patents within a USPC mainclass
uspc_total_num_patents uspcs Total Number of Patents integer Y Total number of patents within a USPC mainclass
wipo_field_id wipos WIPO Technology Field ID integer Y ID of WIPO technology field
wipo_field_title wipos Technology Field Title string Y Description of WIPO technology field
wipo_sector_title wipos Technology Sector Title string Y Description of WIPO technology sector
wipo_sequence wipos Sequence integer Y Order of the WIPO technology field in the list of technology fields for the selected patent