Previous tutorial: 4. Using filters in the Datasets API
Company batches are simple collections of companies you can maintain temporarily or indefinitely.
When created they are empty, but have an assigned UUID you can use to reference it, or you can
supply your own "key" to identify your company batch with. The expiration date can be left unset,
then a default will be used, or you can set it to whatever you like. If you don't want it to ever
be deleted, you can assign it null which means it will last until manually deleted.
The neat thing about these batches is that the UUID or your assigned key they can be used as filters many places in the API.
Let's try to replicate the previous filter using a company batch.
https://api.enin.ai/analysis/v1/company-batch
company_batch_key: Name of the company batch
expiration_timestamp: Set this if company batch should be deleted after a certain date. YYYY-MM-DDTo create a company batch, send an HTTP POST request with data in its body. With the requests library, simply pass your data as the json argument to the post() method, and it will automatically be sent as a JSON payload.
In our payload we will give the batch a name company_batch_key = my_test_batch, and set the expiration_timestamp
to be one day from now.
expiration_timestamp = (datetime.now() + timedelta(days=1)).isoformat()
company_batch = requests.post(
'https://api.enin.ai/analysis/v1/company-batch',
auth=auth,
json={
'company_batch_key': 'my_test_batch',
'expiration_timestamp': expiration_timestamp,
}
).json()
print('expiration_timestamp:', expiration_timestamp)
print_obj(company_batch)
This first prints the supplied expiration_timestamp:
expiration_timestamp: 2020-05-15T18:42:49.668177
... then the server batch representation of the batch you supplied:
{
"uuid": "65ed1de0-0b04-48be-abc1-d8099a0aaed9",
"app_customer_uuid": "85e3e2f9-2114-4836-acda-6d1a30779c65",
"expiration_timestamp": "2020-05-15T18:42:49.668177+00:00",
"company_batch_key": "my_test_batch",
"app_url": null
}
https://api.enin.ai/analysis/v1/company-batchcompany_batches = requests.get(
'https://api.enin.ai/analysis/v1/company-batch',
auth=auth,
).json()
print_obj(company_batches)
If you have only made the one batch in the above example it should list the previous batch
https://api.enin.ai/analysis/v1/company-batch/<company_batch_identifier>/company
[{'uuid': 'f0e01f1e-f977-429f-ac12-0f0418901bfe'}]
Or: [{"org_nr": "914048990", "org_nr_schema": "NO"}]Next, we need to fill this batch with companies:
Here we are POSTing a list with only a single company (using its UUID) to the company batch
we just created. Notice that we saved the new batch object as company_batch and we are using
the generated company batch UUID as part of the request URL.
companies = requests.post(
f"https://api.enin.ai/analysis/v1/company-batch/{company_batch['uuid']}/company",
auth=auth,
json=[
{'uuid': 'f0e01f1e-f977-429f-ac12-0f0418901bfe'},
]
).json()
print_obj(companies)
We didn't have to use the UUIDs for POSTing here. Let's try using company_batch_key we supplied
earlier and the organization numbers from those 50 billion NOK companies we queried earlier.
companies = requests.post(
'https://api.enin.ai/datasets/v1/company-batch/my_test_batch/company',
auth=auth,
json=[
{"org_nr": "914048990", "org_nr_schema": "NO"},
{"org_nr": "914803802", "org_nr_schema": "NO"},
{"org_nr": "917537534", "org_nr_schema": "NO"},
{"org_nr": "923609016", "org_nr_schema": "NO"},
{"org_nr": "927066440", "org_nr_schema": "NO"},
{"org_nr": "990888213", "org_nr_schema": "NO"},
{"org_nr": "991324968", "org_nr_schema": "NO"},
]
).json()
print_obj(companies)
The output from the above request is as follows:
[
{
"name": "HELSE SØR-ØST RHF",
"uuid": "e7564cfd-1a26-464e-ac61-b8b5c9c18f74",
"org_nr": "991324968",
"org_nr_schema": "NO",
"app_url": "https://app.enin.ai/company/e7564cfd-1a26-464e-ac61-b8b5c9c18f74"
},
{ "name": "EQUINOR ENERGY AS", ... },
{ "name": "ESSO NORGE AS", ... },
{ "name": "TOTAL E&P NORGE AS", ... },
{ "name": "HYDRO ALUMINIUM AS", ... },
{ "name": "EXXONMOBIL EXPLORATION AND PRODUCTION NORWAY AS", ... },
{ "name": "EQUINOR ASA", ... }
]
Notice that the post only returned the companies you just POSTed.
https://api.enin.ai/datasets/v1/company-batch/<company_batch_identifier>/companyLet's get all the companies in the batch:
companies = requests.get(
'https://api.enin.ai/datasets/v1/company-batch/my_test_batch/company',
auth=auth,
).json()
print_obj(companies)
This prints out all the entries in the batch. Be careful with printing out all the companies if your batch is too big. You could alternatively save them to a file.
Here is what it will look like:
[
{
"name": "ENIN AS",
"uuid": "f0e01f1e-f977-429f-ac12-0f0418901bfe",
"org_nr": "917540640",
"org_nr_schema": "NO",
"app_url": "https://app.enin.ai/company/f0e01f1e-f977-429f-ac12-0f0418901bfe"
},
{
"name": "HELSE SØR-ØST RHF",
"uuid": "e7564cfd-1a26-464e-ac61-b8b5c9c18f74",
"org_nr": "991324968",
"org_nr_schema": "NO",
"app_url": "https://app.enin.ai/company/e7564cfd-1a26-464e-ac61-b8b5c9c18f74"
},
{ "name": "EQUINOR ENERGY AS", ... },
{ "name": "ESSO NORGE AS", ... },
{ "name": "TOTAL E&P NORGE AS", ... },
{ "name": "HYDRO ALUMINIUM AS", ... },
{ "name": "EXXONMOBIL EXPLORATION AND PRODUCTION NORWAY AS", ... },
{ "name": "EQUINOR ASA", ... }
]
Note that the company batch API endpoints are not special like the datasets API endpoints in that the special filtering and field selection features we've been talking about until now do not apply for the the content of company batches.
In the output above, we see that the first company we inserted (with an UUID of
f0e01f1e-f977-429f-ac12-0f0418901bfe) is still there!
It seems a little off compared to the other companies in that list, so lets just delete it.
https://api.enin.ai/datasets/v1/<company_batch_identifier>/my_test_batch/company/<company_identifier>
company_batch_identifier: Either the UUID or company_batch_key if you provided onecompany_identifier: You can use either the UUID or the organization_number_schema + organization_number (Example: NO917540640)company = requests.delete(
'https://api.enin.ai/datasets/v1/company-batch/my_test_batch/company/NO917540640',
auth=auth,
).json()
print_obj(company)
Now doing a HTTP GET request to https://api.enin.ai/datasets/v1/company-batch/my_test_batch/company
returns the expected 7 organizations:
[
{ "name": "HELSE SØR-ØST RHF", ... },
{ "name": "EQUINOR ENERGY AS", ... },
{ "name": "ESSO NORGE AS", ... },
{ "name": "TOTAL E&P NORGE AS", ... },
{ "name": "HYDRO ALUMINIUM AS", ... },
{ "name": "EXXONMOBIL EXPLORATION AND PRODUCTION NORWAY AS", ... },
{ "name": "EQUINOR ASA", ... }
]
Now that we know how to create and manage company batches, let's use this to filter down the results of a datasets api endpoint.
To do this we simply replace the IN dot notation filter we used earlier with
simply a company_batch_identifier query parameter. Notice how it is not a dot notation filter,
just a regular query parameter. And we can provide either the UUID of the company batch or the key.
accounts = requests.get(
"https://api.enin.ai/datasets/v1/dataset/accounts-composite",
params={
"response_file_type": "csv",
"accounts_type.accounts_type_key": "EQ:annual_company_accounts",
"accounts.accounting_year": "IN:2008,2018",
"company.org_nr_schema": "EQ:NO",
"company_batch_identifier": "my_test_batch", # <--company_batch_identifier
"keep_only_fields": ','.join(
[
"company.name",
"company.org_nr",
"accounts.accounting_year",
"accounts_income_statement.total_operating_income",
]
)
},
auth=auth,
).content.decode()
print(accounts)
As we hoped for this returns the same results as previously:
accounts.accounting_year,company.name,company.org_nr,accounts_income_statement.total_operat ...
2018,EXXONMOBIL EXPLORATION AND PRODUCTION NORWAY AS,914048990,30239000000
2008,EXXONMOBIL EXPLORATION AND PRODUCTION NORWAY AS,914048990,67882000000
2018,ESSO NORGE AS,914803802,31061000000
2008,ESSO NORGE AS,914803802,55560000000
2018,TOTAL E&P NORGE AS,927066440,35091000000
2008,TOTAL E&P NORGE AS,927066440,57122000000
2018,EQUINOR ASA,923609016,483083652000
2008,EQUINOR ASA,923609016,588422000000
2018,HELSE SØR-ØST RHF,991324968,75744464000
2008,HELSE SØR-ØST RHF,991324968,48986731000
2018,EQUINOR ENERGY AS,990888213,214951445000
2008,EQUINOR ENERGY AS,990888213,81474000000
2018,HYDRO ALUMINIUM AS,917537534,52570000000
2008,HYDRO ALUMINIUM AS,917537534,48952000000
The only difference is that there is no upper bound to how large the company batch can be!
Finally, let's clean up the test batch:
company_batch = requests.delete(
'https://api.enin.ai/analysis/v1/company-batch/my_test_batch',
auth=auth,
).json()
print_obj(company_batch)
In addition to explicitly using company batches to fetch data about a list of companies, you can also do so in a single response in two ways. The simplest way is to use a comma separated list of organization numbers or company uuids like this:
https://api.enin.ai/datasets/v1/dataset/company-composite?company.org_nr=IN:985615616,938333572&company.org_nr_schema=NO
However, your URL might become too long for large lists of companies. This brings us to the second method of doing this in one request: You can POST partial company entities as part of a json body like this:
company_composites = requests.get(
"https://api.enin.ai/datasets/v1/dataset/company-composite",
params={
"response_file_type": "csv",
"request_file_type": "json", # json is default, csv also supported
"accounts_type.accounts_type_key": "EQ:annual_company_accounts",
"company.org_nr_schema": "EQ:NO",
},
json=[
{'org_nr': '985615616', 'org_nr_schema': 'NO'},
{'org_nr': '938333572', 'org_nr_schema': 'NO'},
{'uuid': '01cdf33b-fa49-435e-993e-a83dffbd5d31'},
],
auth=auth,
).content.decode()
print(company_composites)
Under the hood this creates a short-lived temporary company batch, which is used immediately to respond to your request
like any batched request would. This method works for all /dataset/{dataset_name} endpoints, and you should always
use partial company entities when you POST, even if it isn't the /v1/dataset/company-composite endpoint.
6. Inspect and batch download paginated data with the Datasets API