Armatis

📦 Armatis parses the website or web API response of Korean parcel delivery service company for tracking the parcel.

Installation

Install Armatis with this following command:

$ pip install armatis

Usage

Armatis is simple to use. Just need to type the delivery company code and the invoice number.

To find the parcel, just use the method find():

from armatis import Armatis

tracker = Armatis('cj', 123456789123)
tracker.find()

You can use the method supported_companies() to find the supported delivery company names and company codes.

tracker.supported_companies()

The returned data of the method find() is like below:

{
	"company": {
		"contact": "1588-1255",
		"name": "CJ대한통운"
	}, 
	"parcel": {
		"receiver": "(주*",
		"sender": "한만*",
		"note": "일반",
		"address": "경기도 성남시 분당구******"
	},
	"tracks": [
		{
			"time": "2016-10-13 18:07:13",
			"status": "간선상차",
			"location": "파주Sub",
			"phone1": "파주Sub(031-960-6566)",
			"phone2": null
		},
		{
			"time": "2016-10-13 21:22:09",
			"status": "집화처리",
			"location": "경기파주",
			"phone1": "경기파주(070-7779-1003)",
			"phone2": null
		},
		{
			"time": "2016-10-14 02:06:39",
			"status": "간선하차",
			"location": "옥천HUB",
			"phone1": null,
			"phone2": null
		}, 
		{
			"time": "2016-10-14 02:17:16",
			"status": "간선하차",
			"location": "옥천HUB",
			"phone1": null,
			"phone2": null
		}, 
		{
			"time": "2016-10-14 02:25:10",
			"status": "행낭포장",
			"location": "옥천HUB",
			"phone1": null,
			"phone2": null
		}, 
		{
			"time": "2016-10-14 04:06:49",
			"status": "간선상차",
			"location": "옥천HUB",
			"phone1": null,
			"phone2": null
		},
		{
			"time": "2016-10-14 11:10:05",
			"status": "간선하차",
			"location": "분당A",
			"phone1": "분당A(031-725-9222)",
			"phone2": null
		},
		{
			"time": "2016-10-14 11:12:07",
			"status": "배달출발",
			"location": "분당대리점a(C15F)",
			"phone1": "분당대리점a(C15F)(031-769-0516)",
			"phone2": "01012345678"
		},
		{
			"time": "2016-10-14 16:44:35",
			"status": "배달완료",
			"location": "분당대리점a(C15F)",
			"phone1": "분당대리점a(C15F)(031-769-0516)",
			"phone2": "01012345678"
		}
	]
}

Supported delivery companies

The following delivery companies are supported currently.

Company	Test existed	Last Updated
CJ대한통운, CVSNet편의점택배	✅	2016-12-10
로젠택배	✅	2016-12-10
현대택배	✅	2016-12-10
한진택배	✅	2016-12-10
KG로지스	✅	2016-12-10
GTX로지스	✅	2017-01-02
우체국택배	✅	2017-01-06
합동택배	✅	2017-01-06
EMS	✅	2017-01-02
KGB택배	✅	2017-01-02

How to add new company

You can make the new delivery company parser easily.

First, create a class which inherit Parser, and implement the method parse().

from armatis.models import Parcel, Track
from armatis.parser import Parser, ParserRequest

class NewCompanyParser(Parser):
    def __init__(self, invoice_number, config):
        super(NewCompanyParser, self).__init__(invoice_number, config)
        # Describe the information about the website or web API provided by the delivery company 
        parser_request = ParserRequest(url='http://thecompany.co.kr/tracking?invno=%s' % self.invoice_number)
        self.add_request(parser_request)
        
    # Actually occurred parsing the website or web API provided above 
    def parse(self, parser):
        tables = parser.find_all('tbody')

        parcel = Parcel()
        parcel.sender = ...         # Sender's name
        parcel.receiver = ...       # Receiver's name
        parcel.address = ...        # Receive address
        parcel.note = ...           # Describe about the parcel
        self.parcel = parcel        # Store the information about the parcel!

        trs = tables[1].find_all('tr')
        for tr in trs:
            track = Track()
            track.status = ...      # Status of the delivery history
            track.time = ...        # Time of the delivery history
            track.location = ...    # Location the parcel where it is 
            track.phone1 = ...      # Contact of the location
            track.phone2 = ...      # Contact of the location
            self.add_track(track)   # Add the tracking information!

And, make a Company instance that describe the company.
Finally, register this Company object with the Parser class you made above.

from armatis import Armatis, Company

tracker = Armatis()

# Make a Company instance that describe the company
the_new_company = Company('새로운회사', 'nc', '1234-5678', [10, 12])
# Register the Company object with the Parser class you made
tracker.parser_manager.register_parser(the_new_company, NewCompanyParser)

Documentation

Completed documentation for Armatis is available on ReadtheDocs.

Contributing

Welcome contributions! If you would like to contribute on Armatis, please follow these steps:

1. Fork this repository
2. Make your changes
3. Install the requirements using pip install -r requirements.txt
4. Submit a pull request after running make ready