Skip to content
master
Go to file
Code

README.md

Reconcile

Enrich your data, adding new columns based on lookups to online services.

Requires Node.

Installing

$ npm install -g reconcile

Alternatively, don't install it and just prepend the below commands with npx.

Usage

$ reconcile <command> <filename>

Where <command> is one of the operations listed in the next section.

Each command will need some parameters specific to what it does to work, which are given using the -p flag. They should be written in Yaml format, for example:

$ reconcile company-numbers-to-company-officer-names input.csv -p 'jurisdiction: gb, companyNumberField: RegisteredCompanyNumber' > output.csv

Note this also uses redirection (>) to send the output into a new CSV file. If you are giving it a value that has spaces in it, you'll need put it in quotes. If, as above, you used single quotes (') around your whole list of parameters, you should use double quotes (") around the value, and vice-versa.

If there are a lot of parameters, it may be more convenient to put them in a separate file, and pass the name of that file to -p.

HTTP requests are automatically retried if they fail, five times by default, but this can be adjusted with the -r flag.

Request caching can be turned on with the -c flag. This will save a copy of each HTTP request in a .reconcile-cache directory. Reconcile always looks for a cached copy of a request before making one itself. Note that if the data is likely to have changed since it was cached, you will still be getting the cached copy -- delete the directory if this is not what you want. Also beware that this directory can become quite large.

If you'd like to include rows where no match was found, or an error was encountered, set the join flag -j to 'outer'.

Commands

Double-press the tab key to autocomplete these names from the command line.


Using OpenCorporates

company-numbers-to-company-details

Use OpenCorporates to look up a list of company numbers and jurisdiction codes, and retrieve various details for each.

Parameters:

  • apiToken An OpenCorporates API token. You are limited to 200 requests per month and 50 per day otherwise. Optional.
  • jurisdiction If all companies have the same jurisdiction you can specify it here instead of in a column. Optional.
  • companyNumberField Company number column. Optional. Default is "companyNumber".
  • companyJurisdictionField Jurisdiction code column. It should use ISO 3166-2 format. Optional. Default is "companyJurisdiction".

Produces a CSV including columns:

  • companyJurisdiction
  • companyName
  • companyIncorporationDate
  • companyDissolutionDate
  • companyType
  • companyStatus
  • companyAddress
  • companyPreviousNames
  • companyAlternativeNames
  • companyBeneficialOwners
  • companyAgentName
  • companyAgentAddress
  • companyActivities

company-numbers-to-company-officer-names

Use OpenCorporates to look up a list of company numbers and jurisdiction codes, and retrieve the names of their officers.

Parameters:

  • apiToken An OpenCorporates API token. You are limited to 200 requests per month and 50 per day otherwise. Optional.
  • jurisdiction If all companies have the same jurisdiction you can specify it here instead of in a column. Optional.
  • companyNumberField Company number column. Optional. Default is "companyNumber".
  • companyJurisdictionField Jurisdiction code column, if any. It should use ISO 3166-2 format. Optional. Default is "companyJurisdiction".

Produces a CSV including columns:

  • companyName
  • officerName
  • officerPosition
  • officerStartDate
  • officerEndDate
  • officerNationality
  • officerOccupation
  • officerAddress (only if an API token is sent)
  • officerDateOfBirth (only if an API token is sent)

company-names-to-company-numbers

Use OpenCorporates to look up a list of company names and find the most likely registration number for each. Beware incorrect matches! Company names are terrible unique identifiers.

Parameters:

  • apiToken An OpenCorporates API token. You are limited to 200 requests per month and 50 per day otherwise. Optional.
  • jurisdiction If all companies have the same jurisdiction you can specify it here instead of in a column. Optional.
  • companyNameField Company name column. Optional. Default is "companyName".
  • companyJurisdictionField Jurisdiction code column, if any. It should use ISO 3166-2 format. Optional. Default is "companyJurisdiction".
  • maximumResults Maximum number of results to include for each name. Optional. Default is 1, maximum is 30, or 100 with an API token.

Produces a CSV including columns:

  • companyJurisdiction
  • companyNumber
  • companyName

individual-names-to-company-officer-names

Use OpenCorporates to look up a list of individual names and find which companies they are officers of (typically either as directors or secretaries).

Parameters:

  • apiToken An OpenCorporates API token. You are limited to 200 requests per month and 50 per day otherwise. Optional.
  • jurisdiction If all individuals have the same jurisdiction you can specify it here instead of in a column. Optional.
  • individualNameField Individual name column. Optional. Default is "individualName".
  • individualDateOfBirthField Individual birth date column. It should use ISO 8601 format. For a range the two dates should be separated with a colon. Optional. Default is "individualDateOfBirth".
  • individualJurisdictionField Jurisdiction code column, if any. It should use ISO 3166-2 format. Optional. Default is "individualJurisdiction".

Produces a CSV including columns:

  • officerName
  • officerPosition
  • officerNationality
  • officerOccupation
  • officerAddress (only if an API token is sent)
  • officerDateOfBirth (only if an API token is sent)
  • companyName
  • companyNumber
  • companyJurisdiction

names-to-company-beneficial-owner-names

Use OpenCorporates to look up a list of names of companies or individuals and find which companies they are the beneficial owner of.

Parameters:

Produces a CSV including columns:

  • ownerName
  • ownerCompanyNumber
  • ownerCompanyJurisdiction
  • ownerBirthDate
  • ownerNationality
  • ownerCountryOfResidence
  • ownerAddress
  • ownerControlMechanisms
  • companyName
  • companyNumber
  • companyJurisdiction

Using Companies House (UK)

uk-company-numbers-to-company-details

Use Companies House to look up a list of company numbers, and retrieve various details for each.

Parameters:

  • apiKey A Companies House API key.
  • companyNumberField Company number column. Optional. Default is "companyNumber".

Produces a CSV including columns:

  • companyName
  • companyUKJurisdiction
  • companyCreationDate
  • companyCessationDate
  • companyType
  • companySubtype
  • companyStatus
  • companyStatusDetail
  • companyAddress
  • companyAddressIsInDispute
  • companyAddressIsUndeliverable
  • companyPreviousNames
  • companySICs
  • companyCanFile
  • companyHasInsolvencyHistory
  • companyHasCharges
  • companyHasBeenLiquidated
  • companyAccountsOverdue
  • companyAnnualReturnOverdue
  • companyPartialDataAvailable
  • companyExternalRegistrationNumber
  • companyLastFullMembersListDate

uk-company-numbers-to-company-beneficial-owner-names

Use Companies House to look up a list of company numbers, and retrieve the names of their beneficial owners.

Parameters:

  • apiKey A Companies House API key.
  • companyNumberField Company number column. Optional. Default is "companyNumber".

Produces a CSV including columns:

  • beneficialOwnerName
  • beneficialOwnerKind
  • beneficialOwnerNaturesOfControl
  • beneficialOwnerName
  • beneficialOwnerTitle
  • beneficialOwnerFirstName
  • beneficialOwnerMiddleNames
  • beneficialOwnerLastName
  • beneficialOwnerKind
  • beneficialOwnerNaturesOfControl
  • beneficialOwnerNotifiedDate
  • beneficialOwnerCeasedDate
  • beneficialOwnerNationality
  • beneficialOwnerAddress
  • beneficialOwnerDateOfBirth
  • beneficialOwnerCountryOfResidence
  • beneficialOwnerIdentificationLegalAuthority
  • beneficialOwnerIdentificationLegalForm
  • beneficialOwnerIdentificationRegisteredPlace
  • beneficialOwnerIdentificationRegisteredCountry
  • beneficialOwnerIdentificationNumber

uk-company-numbers-to-uk-company-officer-ids

Use Companies House to look up a list of company numbers, and retrieve the IDs and names of their officers.

Parameters:

  • apiKey A Companies House API key.
  • companyNumberField Company number column. Optional. Default is "companyNumber".

Produces a CSV including columns:

  • officerID
  • officerName
  • officerRole
  • officerAppointedDate
  • officerResignedDate
  • officerNationality
  • officerOccupation
  • officerAddress
  • officerDateOfBirth
  • officerCountryOfResidence
  • officerFormerNames
  • officerIdentificationType
  • officerIdentificationLegalAuthority
  • officerIdentificationLegalForm
  • officerIdentificationRegisteredPlace
  • officerIdentificationNumber

uk-company-numbers-to-insolvency-cases

Use Companies House to look up a list of company numbers, and retrieve the insolvency cases for each.

Parameters:

  • apiKey A Companies House API key.
  • companyNumberField Company number column. Optional. Default is "companyNumber".

Produces a CSV including columns:

  • companyInsolvencyStatus
  • companyInsolvencyCaseNumber
  • companyInsolvencyCaseType
  • companyInsolvencyCaseWoundUpDate
  • companyInsolvencyCasePetitionedDate
  • companyInsolvencyCaseConcludedWindingUpDate
  • companyInsolvencyCaseDueToBeDissolvedDate
  • companyInsolvencyCaseDissolvedDate
  • companyInsolvencyCaseAdministrationStartedDate
  • companyInsolvencyCaseAdministrationEndedDate
  • companyInsolvencyCaseAdministrationDischargedDate
  • companyInsolvencyCaseVoluntaryArrangementStartedDate
  • companyInsolvencyCaseVoluntaryArrangementEndedDate
  • companyInsolvencyCaseMoratoriumStartedDate
  • companyInsolvencyCaseInstrumentedDate
  • companyInsolvencyCasePractitioners
  • companyInsolvencyCaseNotes

uk-company-numbers-to-charges

Use Companies House to look up a list of company numbers, and retrieve the charges for each.

Parameters:

  • apiKey A Companies House API key.
  • companyNumberField Company number column. Optional. Default is "companyNumber".

Produces a CSV including columns:

  • chargeCode
  • chargeNumber
  • chargeStatus
  • chargePersonsEntitled
  • chargeAcquiredDate
  • chargeCreatedDate
  • chargeDeliveredDate
  • chargeResolvedDate
  • chargeSatisfiedDate
  • chargeCoveringInstrumentDate
  • chargeTransactions
  • chargeParticulars
  • chargeContainsFixedCharge
  • chargeContainsFloatingCharge
  • chargeContainsNegativePledge
  • chargeFloatingChargeCoversAll
  • chargeChargorActingAsBareTrustee
  • chargeHasScottishAlterationsToOrder
  • chargeHasScottishAlterationsToProhibitions
  • chargeHasScottishAlterationsRestrictingProvisions
  • chargeAssetsCeasedReleased
  • chargeClassificationType
  • chargeClassificationDescription
  • chargeSecuredType
  • chargeSecuredDescription

company-names-to-uk-company-numbers

Use Companies House to look up a list of company names and find the most likely registration number for each. Beware incorrect matches! Company names are terrible unique identifiers.

Parameters:

  • apiKey A Companies House API key.
  • companyNameField Company name column. Optional. Default is "companyName".
  • maximumResults Maximum number of results to include for each name. Optional. Default is 1, maximum is 100.

Produces a CSV including columns:

  • companyNumber
  • companyName

individual-names-to-uk-company-officer-ids

Use Companies House to look up a list of individual names and find the ID numbers for each. Many officers will have multiple IDs associated with them. This is limited to bringing back the first 10 pages of matches.

Parameters:

  • apiKey A Companies House API key.
  • individualNameField Individual name column. Optional. Default is "individualName".

Produces a CSV including columns:

  • officerID
  • officerName
  • officerBirthMonth
  • officerBirthYear
  • officerAppointments
  • officerAddress

uk-company-officer-ids-to-company-numbers

Use Companies House to look up a list of officer IDs, and retrieve the company numbers for their appointments.

Parameters:

  • apiKey A Companies House API key.
  • officerIDField Officer ID column. Optional. Default is "officerID".

Produces a CSV including columns:

  • companyNumber
  • companyName
  • companyStatus
  • officerID
  • officerName
  • officerRole
  • officerAppointedDate
  • officerResignedDate
  • officerNationality
  • officerOccupation
  • officerAddress
  • officerCountryOfResidence

Using Land Registry (UK)

uk-land-title-numbers-to-addresses

Look up UK Land Registry title numbers (such as the result of a PN1 search), and find their addresses.

Parameters:

  • titleNumberField Title number field. Optional. Default is "titleNumber".

Produces a CSV including columns:

  • titleAddress
  • titleTenure Leasehold or freehold.

Using SEC Edgar (US)

sec-ciks-to-sec-filings

Use the SEC Edgar company filings search to take a list of CIKs, or 'central index keys', an identifier given by the SEC to those who have filed disclosures, and retrieve all their filings.

Parameters:

  • cikField CIK column. Optional. Default is "cik".
  • filingType Type of filings to include, eg. 10-K. Optional. Default is all filings.
  • includeAll Set true to include all filed documents, instead of just the first. Optional. Default is first only.

Produces a CSV including columns:

  • filingDate
  • filingType
  • filingDetail
  • filingDocumentType
  • filingDocumentDescription
  • filingDocument

names-to-sec-ciks

Use the SEC Edgar CIK lookup to take a list of names of companies, funds, or individuals and find the most likely CIK, or 'central index key', an identifier given by the SEC to those who have filed disclosures. Beware incorrect matches! Names are terrible unique identifiers.

Parameters:

  • nameField Name column. Optional. Default is "name".
  • maximumResults Maximum number of results to include for each name. Optional. Default is 1, maximum is 100.

Produces a CSV including columns:

  • name
  • cik

Using Equasis

ship-imo-numbers-to-ship-details

Use Equasis to take a list of ship IMO numbers, and retrieve all their connected companies, as well as other details. Note Equasis only allows around 500 lookups per day. If you exceed that two days in a row you get blocked for seven days.

Parameters:

  • email The email address for a registered Equasis account.
  • password The password for a registered Equasis account.
  • shipIMONumberField Ship IMO number field. Optional. Default is "shipIMONumber".

Produces a CSV including columns:

  • shipName
  • shipCallSign
  • shipMMSI
  • shipTonnage
  • shipDWT
  • shipType
  • shipBuildYear
  • shipFlag
  • shipStatus
  • shipFormerNames
  • shipFormerFlags
  • shipCompanyRole
  • shipCompanyName
  • shipCompanyDate

ship-mmsi-numbers-to-ship-details

Use Equasis to take a list of ship MMSI numbers, and retrieve all their connected companies, as well as other details. Note Equasis only allows around 500 lookups per day. If you exceed that two days in a row you get blocked for seven days.

Parameters:

  • email The email address for a registered Equasis account.
  • password The password for a registered Equasis account.
  • shipMMSINumberField Ship MMSI number field. Optional. Default is "shipMMSINumber".

Produces a CSV including columns:

  • shipName
  • shipCallSign
  • shipMMSI
  • shipTonnage
  • shipDWT
  • shipType
  • shipBuildYear
  • shipFlag
  • shipStatus
  • shipFormerNames
  • shipFormerFlags
  • shipCompanyRole
  • shipCompanyName
  • shipCompanyDate

ship-names-to-ship-imo-numbers

Use Equasis to take a list of ship names, and retrieve their IMO numbers. Note Equasis only allows around 500 lookups per day. If you exceed that two days in a row you get blocked for seven days.

Parameters:

  • email The email address for a registered Equasis account.
  • password The password for a registered Equasis account.
  • shipNameField Ship name field. Optional. Default is "shipName".

Produces a CSV including columns:

  • shipIMONumber
  • shipName
  • shipTonnage
  • shipType
  • shipBuildYear
  • shipFlag

Using ITU Mars

ship-mmsi-numbers-to-ship-radio-station-details

Use the International Telecommunication Union's database of ship-based radio stations (ITU Mars) to take a list of ship MMSI numbers, and retrieve their details, including the owner.

Parameters:

  • shipMMSINumberField Ship MMSI number field. Optional. Default is "shipMMSINumber".

Produces a CSV including columns:

  • shipName
  • shipCallSign
  • shipIdentificationNumber
  • shipOwner
  • shipFormerName
  • shipTonnage
  • shipPersonCapacity

About

Enriches your data, adding new columns based on lookups to online services

Resources

You can’t perform that action at this time.