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.
First, we need to make a company batch using a HTTP POST request. These requests have a body we
can supply data via, instead of a through the URL as a query parameter. In the requests library
we can simply supply an object to the post() method as the json argument and it will automatically
be interpreted as JSON HTTP POST request.
Alright, let's make our first company batch and name it my_test_batch, and set the expiration_timestamp
to be one day from now. The format for the timestamp follows python's implementation of
ISO8601. This means you can specify it down to the millisecond,
or just supply a date of the form YYYY-MM-DD.
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
}
You can also find existing batches by listing all the available company batches for the
customer you represent by doing a HTTP GET request to the company batch API endpoint:
company_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 as follows:
[
{
"uuid": "e11d6828-e3b1-4935-9dcc-4818c4ef5e4e",
"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
}
]
Next, we need to fill this batch with companies:
companies = requests.post(
'https://api.enin.ai/analysis/v1/company-batch/{company_batch_identifier}/company'.format(
company_batch_identifier=company_batch['uuid']
),
auth=auth,
json=[
{'uuid': 'f0e01f1e-f977-429f-ac12-0f0418901bfe'},
]
).json()
print_obj(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. In this case we are not using query
parameters, but rather the URL itself. You can build URLs like this using string interpolation of
some kind. In this case we are using python's str.format(...) function for this purpose.
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)
This time we didn't need to use string interpolation, and using the organization numbers makes
things just that more easy to work with. Just remember that the org_nr_schema is required.
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. Let's return them all:
companies = requests.get(
'https://api.enin.ai/datasets/v1/company-batch/my_test_batch/company',
auth=auth,
).json()
print_obj(companies)
This give all the entries in the batch:
[
{
"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.
This can be done with either the UUID or its organization number, both represent a "company
identifier" and can be used interchangeably if you see the argument named company_identifier
in the generated API documentation. Just make sure you prefix the organization number with
the organization number schema (NO for Brønnøysundregistrene in Norway).
company = requests.delete(
'https://api.enin.ai/datasets/v1/company-batch/my_test_batch/company/NO917540640',
auth=auth,
).json()
print_obj(company)
Also deletes returns to you the object just deleted:
{
"uuid": "f0e01f1e-f977-429f-ac12-0f0418901bfe",
"name": "ENIN AS",
"org_nr": "917540640",
"org_nr_schema": "NO",
"app_url": "https://app.enin.ai/company/f0e01f1e-f977-429f-ac12-0f0418901bfe"
}
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 one to filter datasets API
endpoints. 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 that it also is postfixed with _identifier, this indicates
that it accepts multiple forms of keys. In this case both the UUID of the company batch and
the company_batch_key we supplied earlier. Let's use the latter:
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",
"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)
We can also do this by using the company batch UUID.
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.