abn-lookup-service

abn-lookup-service

A python client to interact with ABN Lookup services

This library provides a Python interface to the Australian Business Register (ABR) XML Search API. All API methods are based on the official ABR documentation.

• abn-lookup-service
  • Installation
  • Authentication
    • CLI
  • Usage
    • Python Library
      • Basic Example
      • Advanced Example
    • Supported Methods
      • SearchByABN (docs)
      • SearchByASIC (docs)
      • SearchByName (docs)
      • SearchByNameAdvanced (docs)
      • SearchByPostcode (docs)
      • SearchByABNStatus (docs)
      • SearchByUpdateEvent (docs)
      • SearchByRegistrationEvent (docs)
      • SearchByCharity (docs)
  • Development
    • Testing
      • Docker
      • Host Machine

Installation

python3 -m pip install 'abn-lookup-service @ git+https://github.com/tmck-code/abn-lookup-service'

Authentication

You'll need an ABN Lookup GUID from the Australian Business Register. Set it as an environment variable:

export ABN_LOOKUP_GUID="your-guid-here"

CLI

The package includes a command-line interface:

# Search by ABN
abn-lookup-service abn --abn 53004085616

# Search by name
abn-lookup-service name --name "Telstra" --state "VIC" --limit 5

# Search by postcode
abn-lookup-service postcode --postcode "3000" --state "VIC"

# Advanced name search
abn-lookup-service name-advanced --name "Commonwealth Bank" --state "NSW" --legalName "Y"

Run with --help to see all available commands and options:

abn-lookup-service --help

usage: lookup.py [-h] {abn-status,charity,registration-event,update-event,name,abn,asic,postcode,name-advanced} ...

ABN Lookup Client

positional arguments:
  {abn-status,charity,registration-event,update-event,name,abn,asic,postcode,name-advanced}
    abn-status          Search by ABN status
    charity             Search by charity
    registration-event  Search by registration event
    update-event        Search by update event
    name                Search by name
    abn                 Search by ABN
    asic                Search by ASIC
    postcode            Search by postcode
    name-advanced       Advanced search by name

options:
  -h, --help            show this help message and exit

abn-lookup-service name --help

usage: lookup.py name [-h] --name NAME --state {NSW,ACT,VIC,QLD,SA,WA,TAS,NT} [--limit LIMIT]

options:
  -h, --help            show this help message and exit
  --name NAME           Name to search for
  --state {NSW,ACT,VIC,QLD,SA,WA,TAS,NT}
                        State to filter results by
  --limit LIMIT         Maximum number of results to return

Usage

Python Library

Basic Example

from abn_lookup_service.lookup import ABNLookupClient
import os

# Initialize the client
client = ABNLookupClient(authentication_guid=os.environ['ABN_LOOKUP_GUID'])

# Search by ABN
for result in client.search_by_abn('53004085616'):
    print(result)

# Search by business name
for result in client.search_by_name(name='Telstra', state='VIC'):
    print(result)

# {"ABN": {"identifierValue": "53653884756", "identifierStatus": "Active"}, "mainName": {"organisationName": "MOONTH MOTORS PTY LTD", "score": "98", "isCurrentIndicator": "Y"}, "mainBusinessPhysicalAddress": {"stateCode": "VIC", "postcode": "3031", "isCurrentIndicator": "Y"}}
# ...

Advanced Example

from abn_lookup_service.lookup import ABNLookupClient
import os

client = ABNLookupClient(authentication_guid=os.environ['ABN_LOOKUP_GUID'])

# Advanced name search with filters
results = client.search_by_name_advanced(
    name='Commonwealth Bank',
    state='NSW',
    legalName='Y',
    minimumScore=80,
    maxSearchResults=10
)

for result in results:
    # Access result fields
    abn = result.get('ABN', {}).get('identifierValue')
    name = result.get('mainName', {}).get('organisationName')
    print(f"ABN: {abn}, Name: {name}")

# ABN: 48045546848, Name: COMMONWEALTH BANK OF AUSTRALIA
# ABN: 53004085616, Name: COMMONWEALTH BANK OF AUSTRALIA
# ...

Supported Methods

SearchByABN (docs)

Search for an entity by ABN.

Parameters:

• abn (str, required): The ABN to search for
• includeHistoricalDetails (str, optional): 'Y' or 'N' (default: 'N')

SearchByASIC (docs)

Search for an entity by ASIC number (ACN, ARBN, ARSN, ARFN).

Parameters:

• asic (str, required): The ASIC number to search for
• includeHistoricalDetails (str, optional): 'Y' or 'N' (default: 'N')

SearchByName (docs)

Search for entities by name (simple protocol).

Parameters:

• name (str, required): Name to search for
• postcode (str, optional): Filter by postcode
• legalName (str, optional): 'Y' to search legal names only
• businessName (str, optional): 'Y' to search business names only
• tradingName (str, optional): 'Y' to search trading names only
• state (str, optional): Filter by state (NSW, ACT, VIC, QLD, SA, WA, TAS, NT)

SearchByNameAdvanced (docs)

Advanced search for entities by name with additional filters.

Parameters:

• name (str, required): Name to search for
• postcode (str, optional): Filter by postcode
• legalName (str, optional): 'Y' to search legal names only
• businessName (str, optional): 'Y' to search business names only
• tradingName (str, optional): 'Y' to search trading names only
• state (str, optional): Filter by state
• searchWidth (str, optional): Search width (narrow, typical, wide)
• minimumScore (int, optional): Minimum matching score (0-100)
• maxSearchResults (int, optional): Maximum number of results to return
• activeABNsOnly (str, optional): 'Y' to return only active ABNs

SearchByPostcode (docs)

Search for entities by postcode.

Parameters:

• postcode (str, required): The postcode to search for

SearchByABNStatus (docs)

Search for entities by ABN status.

Parameters:

• postcode (str, optional): Filter by postcode
• activeABNsOnly (str, optional): 'Y' to return only active ABNs
• currentGSTRegistrationOnly (str, optional): 'Y' to return only GST registered entities
• entityTypeCode (str, optional): Filter by entity type code

SearchByUpdateEvent (docs)

Search for entities by update event.

Parameters:

• updatedate (str, required): Update date (YYYY-MM-DD format)
• postcode (str, optional): Filter by postcode
• state (str, optional): Filter by state
• entityTypeCode (str, optional): Filter by entity type code

SearchByRegistrationEvent (docs)

Search for entities by registration event.

Parameters:

• month (str, required): Month (1-12)
• year (str, required): Year (YYYY format)
• postcode (str, optional): Filter by postcode
• state (str, optional): Filter by state
• entityTypeCode (str, optional): Filter by entity type code

SearchByCharity (docs)

Search for charities.

Parameters:

• postcode (str, optional): Filter by postcode
• state (str, optional): Filter by state
• charityTypeCode (str, optional): Filter by charity type code
• concessionTypeCode (str, optional): Filter by concession type code

Development

This doc section is for developers contributing to the project.

Testing

Docker

Build the docker image

 docker build -f test/Dockerfile -t abn-lookup-service .

Run the tests with

docker run \
    -it \
    -v "$PWD":/app \
    abn-lookup-service:latest \
    bash -c 'pytest -vv test'

Host Machine

uv sync --all-groups
. .venv/bin/activate

pytest -vv -s test/