contactlookup

contactlookup

Self hosted contacts API for searching through a VCF file for contact records

Installation

Using pip:

pip install contactlookup

Using poetry:

poetry add contactlookup

Using pipenv:

pipenv install contactlookup

Quick Start

Running as a Docker container

Serve the contacts in the accompanying contacts.vcf file:

docker build -t contactlookup .
docker run -p 8000:8000 contactlookup # This uses the contacts.vcf file in the container
# Daemonize the container
docker run -d -p 8000:8000 contactlookup

If you want to use a different VCF file, you can mount it as a volume:

docker run -d -p 8000:8000 -v /path/to/contacts.vcf:/app/contacts.vcf contactlookup

:warning: The VCF file must be mounted at /app/contacts.vcf in the container.

To stop the container:

docker ps # Get the container ID
docker stop <container_id>

Running as a CLI application

As a script:

contactlookup --help
contactlookup # Start the API server, and serve the contacts in the accompanying contacts.vcf file
contactlookup -f /path/to/contacts.vcf # Start the API server, and serve the contacts in the VCF file

As a module:

python -m contactlookup --help

Using the API

You can search for contacts by

• first name,
• phone number, or
• email address.

The search is case-insensitive. Partial matches are not yet supported.

Search using web browser

Open your web browser and navigate to http://localhost:8000/docs to see the API documentation. Depending on your setup, you may need to replace localhost.

Search using curl

Search by email

curl -X 'GET' \
  'http://localhost:8000/contacts/email/[e-mail]' \
  -H 'accept: application/json'

Search by phone number

curl -X 'GET' \
  'http://localhost:8000/contacts/phone/[phone]' \
  -H 'accept: application/json'

The use of +, -, ., and () in the phone number is optional. Response:

{
    "contacts": [
        {
            "id": 1,
            "first_name": "KRISTEN",
            "last_name": "PEREZ",
            "other_names": null,
            "company": "Crescendo Associates",
            "title": null,
            "nickname": "NICKNAME",
            "birthday": "1966-08-19",
            "phone_numbers": [
                {
                    "id": null,
                    "number": "7194259182505",
                    "contact_id": 1,
                    "type": null
                },
                {
                    "id": null,
                    "number": "9935478840782",
                    "contact_id": 1,
                    "type": null
                }
            ],
            "addresses": [
                {
                    "id": null,
                    "street": "36346 Hall Stream",
                    "city": "CHRISTOPHERSTAD",
                    "state": "CA",
                    "postal_code": "73297",
                    "contact_id": 1,
                    "type": null,
                    "country": "USA"
                },
                {
                    "id": null,
                    "street": "196 Purple Sage Cres",
                    "city": "WINNIPEG",
                    "state": "MB",
                    "postal_code": "R3X 1V7",
                    "contact_id": 1,
                    "type": null,
                    "country": "CA"
                }
            ],
            "emails": [
                {
                    "id": null,
                    "email": "[e-mail]",
                    "type": null,
                    "contact_id": 1
                }
            ]
        }
    ]
}

Search by first name

curl -X 'GET' \
  'http://localhost:8000/contacts/fname/jeff' \
  -H 'accept: application/json'

Results are returned in JSON format:

{
    "contacts": [
        {
            "id": 3,
            "first_name": "JEFF",
            "last_name": "",
            "other_names": null,
            "company": "Viagenie",
            "title": null,
            "nickname": null,
            "birthday": "1949-01-29",
            "phone_numbers": [
                {
                    "id": null,
                    "number": "3632144414254",
                    "contact_id": 3,
                    "type": null
                }
            ],
            "addresses": [
                {
                    "id": null,
                    "street": "2360 Bean Tunnel",
                    "city": "SOUTH JAMES",
                    "state": "DC",
                    "postal_code": "96916",
                    "contact_id": 3,
                    "type": null,
                    "country": "MONTSERRAT"
                },
                {
                    "id": null,
                    "street": "26767 Khan Dam",
                    "city": "EAST MARISAMOUTH",
                    "state": "MA",
                    "postal_code": "26701",
                    "contact_id": 3,
                    "type": null,
                    "country": "BRAZIL"
                },
                {
                    "id": null,
                    "street": "63932 Natasha Fords",
                    "city": "DEBRAVIEW",
                    "state": "VT",
                    "postal_code": "22957",
                    "contact_id": 3,
                    "type": null,
                    "country": "NAMIBIA"
                }
            ],
            "emails": [
                {
                    "id": null,
                    "email": "[e-mail]",
                    "type": null,
                    "contact_id": 3
                },
                {
                    "id": null,
                    "email": "[e-mail]",
                    "type": null,
                    "contact_id": 3
                },
                {
                    "id": null,
                    "email": "[e-mail]",
                    "type": null,
                    "contact_id": 3
                }
            ]
        },
        {
            "id": 4,
            "first_name": "JEFF",
            "last_name": "NEWMAN",
            "other_names": null,
            "company": "Hollywood",
            "title": null,
            "nickname": null,
            "birthday": "1955-03-29",
            "phone_numbers": [
                {
                    "id": null,
                    "number": "161555531122",
                    "contact_id": 4,
                    "type": null
                }
            ],
            "addresses": [
                {
                    "id": null,
                    "street": "123 Hollywood St",
                    "city": "BEVERLEY-HILLS",
                    "state": "CA",
                    "postal_code": "22957",
                    "contact_id": 4,
                    "type": null,
                    "country": "USA"
                }
            ],
            "emails": [
                {
                    "id": null,
                    "email": "[e-mail]",
                    "type": null,
                    "contact_id": 4
                }
            ]
        }
    ]
}