Clause and Definition Searches
Sometimes you want to search only specific sections of a document. You can do this with clause and definition. And you can search within clause and definition, by adding additional logic as shown below.
There are two types of searches possible with clause and definition:
- nested search, aka search within, explained below
- a list of terms terms, explained here
Import Note on Definition
definitionis labelledDictionaryon the screen, but you writedefinitionin the code.
The easy way to create these queries is create it in the screen then type the equivalent criteria into the API JSON payload. Think of that as a wizard to help you construct the query.
Let's take a look at an example.
Nested Search, aka Search Within
Use the screen to select the documents you would like to search. As you add search criteria it updates the URL In the browser, adding query parameters. You can copy that so that you can replicate the exact search in code, except you cannot use all the text operators available in the API in the screens. So add those manually.
Here is an example. Click the URL below to see the search we describe below:
You can see that these filters were set by clicking the items at the top of the screen and then selecting values from the dropdown boxes on the left.
In Clause
- Whereas = Agreement
- Notices = Limited
- Generally = Partnership
In Dictionary
- Person = partnership
- Subsidiary = Equity
- Business Day = Sunday
Filing Year: 1996 - 2022
You can only search within what you have selected as a filter if it says Clause or Dictionary. You can see that as the field on the screen will actually say search within, prompting you to type over it with some search criteria.
For example, if you pick clause Officer's Certificate it lets you type a string to search for within that.
JSON that Matches the Screen
The JSON that matches that screen above looks like this. Notice that the logical operator between each line in clause and definition is OR (It is implied, meaning not explicitly written.) meaning any of those items that match will be included.
{
"query": {
"q": "",
"clause": {
"WHEREAS": "Agreement",
"Notices": "Limited",
"Generally": "Partnership"
},
"definition": {
"Person": "partnership",
"Subsidiary": "Equity",
"Business Day": "Sunday"
},
"filing_year": {
"max": 2022,
"min": 1996
}
}
}
Results
See the results below.
Remember to look at the Response Attributes section for an explanation of some of the attributes added to the search results.
Notice that the snippet contains an excerpt of the entire document that matches the text in your filter. For searches within searches, like clause and definitions, those show up in the hit and inner_hits sections in the snippets shown there.
{
"_index": "contract",
"_type": "_doc",
"_id": "en/3QS3HcUIP2o",
"_score": 32.41574,
"_source": {
"snippet": "THIS SECOND AMENDED AND RESTATED AGREEMENT OF LIMITED PARTNERSHIP (this \u201cAgreement\u201d) of TAU OPERATING PARTNERSHIP, L.P. heretofore known as American Realty Capital Operating Partnership, L.P. (the \u201cPartnership\u201d), dated as of [ \u02dc ], 2012 and to be effective as of the Effective Date (as defined below), is entered into among [Merger Sub], a Maryland corporation (in its capacity as general partner of the Partnership, together with its successors and permitted assigns that are admitted to the Partnership as a general partner of the Partnership in accordance with the terms hereof, the \u201cGeneral Partner\u201d), as successor to American Realty Capital Trust, Inc., a Maryland corporation (the \u201cPrevious General Partner\u201d), the Persons whose names are set forth on Exhibit A attached hereto, as limited partners, and Realty Income Corporation, a Maryland corporation (the \u201cCompany\u201d), for the sole purpose of agreeing to the provisions in Sections 7.02 and 8.04 and Article XIII hereof.",
"group_size": 2,
"group_id": "3QS3HcUIP2o",
"filing_date": "2012-09-06",
"jurisdiction": {
"name": "Maryland",
"value": "maryland-us"
},
"name": "AGREEMENT AND PLAN OF MERGER By and Among REALTY INCOME CORPORATION, TAU ACQUISITION LLC and AMERICAN REALTY CAPITAL TRUST, INC. Dated as of September 6, 2012",
"industry": {
"name": "Real estate",
"value": "real-estate"
},
"company": {
"name": "American Realty Capital Trust, Inc.",
"value": "1410997"
},
"category": {
"name": "Agreement and Plan of Merger",
"value": "agreement-and-plan-of-merger"
}
},
"inner_hits": {
"definition:Business Day": {
"hits": {
"total": {
"value": 1,
"relation": "eq"
},
"max_score": 8.161037,
"hits": [
{
"_index": "contract",
"_type": "_doc",
"_id": "en/3QS3HcUIP2o",
"_nested": {
"field": "sections",
"offset": 325
},
"_score": 8.161037,
"_source": {
"snippet": "shall mean any day other than a Saturday, Sunday or a day on which all banking institutions in New York, New York are authorized or obligated by Law or executive order to close.",
"name": "Business Day",
"type": "definition",
"value": "business-day"
}
}
]
}
},
"clause:Notices": {
"hits": {
"total": {
"value": 1,
"relation": "eq"
},
"max_score": 2.8227234,
"hits": [
{
"_index": "contract",
"_type": "_doc",
"_id": "en/3QS3HcUIP2o",
"_nested": {
"field": "sections",
"offset": 304
},
"_score": 2.8227234,
"_source": {
"snippet": "All communications required or permitted under this Agreement shall be in writing and shall be deemed to have been given when delivered personally or upon deposit in the United States mail, registered, postage prepaid return receipt requested, to the Partners at the addresses set forth in Exhibit A attached hereto, as it may be amended or restated from time to time; provided, however, that any Partner may specify a different address by notifying the General Partner in writing of such different address. Notices to the General Partner and the Partnership shall be delivered at or mailed to the Partnership\u2019s office address set forth in Section 2.03 hereof. The General Partner and the Partnership may specify a different address by notifying the Limited Partners in writing of such different address.",
"name": "Notices",
"type": "clause",
"value": "notices"
}
}
]
}
},
"definition:Subsidiary": {
"hits": {
"total": {
"value": 1,
"relation": "eq"
},
"max_score": 6.04683,
"hits": [
{
"_index": "contract",
"_type": "_doc",
"_id": "en/3QS3HcUIP2o",
"_nested": {
"field": "sections",
"offset": 535
},
"_score": 6.04683,
"_source": {
"snippet": "means, with respect to any Person, any corporation or other entity of which a majority of (i) the voting power of the voting equity securities or (ii) the outstanding equity interests is owned, directly or indirectly, by such Person.",
"name": "Subsidiary",
"type": "definition",
"value": "subsidiary"
}
}
]
}
},
"clause:Generally": {
"hits": {
"total": {
"value": 1,
"relation": "eq"
},
"max_score": 6.8073606,
"hits": [
{
"_index": "contract",
"_type": "_doc",
"_id": "en/3QS3HcUIP2o",
"_nested": {
"field": "sections",
"offset": 227
},
"_score": 6.8073606,
"_source": {
"snippet": "Partnership Interests shall be represented by Partnership Units. Initially, following the Effective Date all Partnership Units shall be designated as either \u201cClass A Common Units\u201d (\u201cClass A Common Units\u201d), Class B Common Units (\u201cClass B Common Units\u201d) or \u201cPreferred Units\u201d (\u201cPreferred Units\u201d). Except as expressly provided herein, Class A Common Units and Class B Common Units shall entitle the holders thereof to equal rights under this Agreement. Notwithstanding anything to the contrary in this Agreement, any Partnership Units issued to the General Partner, the Partnership or any Affiliate of the General Partner shall be Class B Common Units, and any Partnership Units acquired by the General Partner, the Partnership or any Affiliate of the General Partner from any Limited Partner pursuant to Sections 8.04, 8.05 or 8.06 hereof or otherwise, shall automatically be converted from a Class A Common Unit or Preferred Unit to a Class B Common Unit.",
"name": "Generally",
"type": "clause",
"value": "generally"
}
}
]
}
},
"definition:Person": {
"hits": {
"total": {
"value": 3,
"relation": "eq"
},
"max_score": 6.1596103,
"hits": [
{
"_index": "contract",
"_type": "_doc",
"_id": "en/3QS3HcUIP2o",
"_nested": {
"field": "sections",
"offset": 379
},
"_score": 6.1596103,
"_source": {
"snippet": "shall mean an individual, corporation, partnership, limited partnership, limited liability company, person (including a \u201cperson\u201d as defined in Section 13(d)(3) of the Exchange Act), trust, association or other entity or a Governmental Authority or a political subdivision, agency or instrumentality of a Governmental Authority.",
"name": "Person",
"type": "definition",
"value": "person"
}
}
# Search in List
You can search `clause` and `definition` using a list. The list is given as JSON keys with the value equal to "". Here are two examples, Notice from the format you cannot have both a `q` text query and the `definition` or `clause` query in the same expression.
```{
"query": {
"definition": {
"Person": "",
"Business": "",
"Affiliate": ""
}
}
}
{
"query": {
"clause": {
"WHEREAS": "",
"IN WITNESS WHEREAS": "",
"Governing Law": ""
}
}
}
Python Example
Here is a Python example.
To check any query, look at the inner_hits section of the JSON response. That is only present if your query matched.
import json
import requests
url='https://www.lawinsider.com/api/v1alpha/search?token=<token>' \
query={
"query": {
"definition": {
"Person": "",
"Business": "",
"Affiliate": ""
}
}
}
print(json.dumps(query),"\n")
rsp=requests.post(url=url,json=query )
for k in rsp.json()['hits']['hits']:
print(json.dumps(dict(k),indent=4),"\n")
Results
Produces this output:
{
"_index": "contract",
"_type": "_doc",
"_id": "en/8yCuLWXi1mY",
"_score": 29.37838,
"_source": {
"snippet": "This Business Combination Agreement, dated May 25, 2023 (this \u201cAgreement\u201d), is made and entered into by and among Bridgetown Holdings Limited, a Cayman Islands exempted company limited by shares (\u201cAcquiror\u201d), MoneyHero Limited (formerly known as Hyphen Group Limited), a Cayman Islands exempted company limited by shares (\u201cPubCo\u201d), Gemini Merger Sub 1 Limited, a Cayman Islands exempted company limited by shares and a direct wholly-owned Subsidiary of PubCo (\u201cMerger Sub 1\u201d), Gemini Merger Sub 2 Limited, a Cayman Islands exempted company limited by shares and a direct wholly-owned Subsidiary of PubCo (\u201cMerger Sub 2\u201d) and CompareAsia Group Capital Limited, a Cayman Islands exempted company limited by shares (the \u201cCompany\u201d).",
"group_size": 2,
"group_id": "65pjqhWMPAI",
"filing_date": "2023-05-25",
"jurisdiction": {
"name": "Delaware",
"value": "delaware-us"
},
"name": "BUSINESS COMBINATION AGREEMENT by and among BRIDGETOWN HOLDINGS LIMITED, MONEYHERO LIMITED, GEMINI MERGER SUB 1 LIMITED, GEMINI MERGER SUB 2 LIMITED, and COMPAREASIA GROUP CAPITAL LIMITED dated May 25, 2023",
"industry": {
"name": "Blank checks",
"value": "blank-checks"
},
"company": {
"name": "Bridgetown Holdings LTD",
"value": "1815086"
},
"category": {
"name": "Business Combination Agreement",
"value": "business-combination-agreement"
}
},
"inner_hits": {
"definition:Business": {
"hits": {
"total": {
"value": 3,
"relation": "eq"
},
"max_score": 0.0,
"hits": [
{
"_index": "contract",
"_type": "_doc",
"_id": "en/8yCuLWXi1mY",
"_nested": {
"field": "sections",
"offset": 699
},
"_score": 0.0,
"_source": {
"snippet": "means PubCo and its Subsidiaries\u2019 business of operating a web or application-based marketplace, community, brokerage or aggregator service specialized in fintech and financial services and comparing banking, insurance, telecommunication, utility or other personal finance products and/or providing platform- or software-as-a-service solutions;",
"name": "Business",
"type": "definition",
"value": "business"
}
},
⚫⚫⚫
"definition:Person": {
"hits": {
"total": {
"value": 7,
"relation": "eq"
},
"max_score": 0.0,
"hits": [
{
"_index": "contract",
"_type": "_doc",
"_id": "en/8yCuLWXi1mY",
"_nested": {
"field": "sections",
"offset": 558
},
"_score": 0.0,
"_source": {
"snippet": "means any individual, firm, corporation, partnership, limited liability company, incorporated or unincorporated association, joint venture, joint stock company, Governmental Authority or instrumentality or other entity of any kind.",
"name": "Person",
⚫⚫⚫
"definition:Affiliate": {
"hits": {
"total": {
"value": 5,
"relation": "eq"
},
"max_score": 0.0,
"hits": [
{
"_index": "contract",
"_type": "_doc",
"_id": "en/8yCuLWXi1mY",
"_nested": {
"field": "sections",
"offset": 478
},
"_score": 0.0,
"_source": {
"snippet": "means, with respect to any specified Person, any Person that, directly
Finding Errors
One complication with writing queries is the API will not throw an error when you send it something that has syntax errors or is just not logical.
Instead, if you make an error in the query syntax then the program will either return HTML or it will return incomplete results like shown below.
The sample below is incomplete because there is no snippet attribute or hit, which is where it shows items that matched the query. And if it shows HTML instead of JSON then you know you sent something that is very much spelled wrong, like a missing comma or colon.
{
"_index": "category",
"_type": "_doc",
"_id": "en/note-agreement",
"_score": 45.444447,
"_source": {
"group_id": "note-agreement",
"name": "Note Agreement"
}
}
{
"_index": "category",
"_type": "_doc",
"_id": "en/participant-agreement",
"_score": 45.444447,
"_source": {
"group_id": "participant-agreement",
"name": "Participant Agreement"
}
}
Updated over 1 year ago