Phonebook - a text based phone book search app on android

Created On: 2016-08-11

What is phonebook?

It's an app for android device, that allows you to upload your plain text contact file from your computer, and search contact on your phone. It's designed for people who likes to keep all their contacts in a text file. The file format is very flexible and it's documented below.

Where to install it?

You can get it from Google Play.

How to use it?

  • Install the app. Sign in using your google account.
  • Get user id and api token from the app, then upload a contact file on your computer. You can create a crontab (scheduled task) to do the upload daily to post updates of the file.

    Get user id and api token from side bar:


    Here is how to upload a contact file using curl:

    curl -H "X-Auth-UserId: $YOUR_USER_ID" \
         -H "X-Auth-Token: $YOUR_API_TOKEN" \
         -X POST --data-binary "@/path/to/contact-file.txt" \
  • Search your contacts on phone.

    Example screenshot:


Contact file format.

Contact file format is very flexible. Each contact takes one line. Empty lines are ignored. The first word in the line is parsed as contact name. Everything else is metadata that describes the contact. You may use comma or semicolon to separate fields for the contact.

Here is an example contact file:

张三 138 1234 5678, 中信银行 citic bank 北京分行 零售客户经理;

小陈 159 9876 5432; 张三的老婆

苏通卡; 海门客服中心; G40沪陕(通启高速公路)海门收费站; 0513-82363051; 周一至周日 9:00-17:00(法定节假日除外); 业务内容包括:苏通卡和电子标签的销售、发行、安装、充值、变更、挂失、解挂等全部业务。 省内:96777, 省外: 025-96777

中礼鲜花 400-8888-500 城市市区基本都可以当天送到。

air china 国航知音服务热线: 95583, 4006-100-666

Phone numbers and email addressed will be parsed and presented in a nicer way. The raw text will be available when searching.

When doing a search, everything in the contact file will be matched on.

Phonebook API

API endpoint:

  • POST /api/phone-file
    • Request: request body should be the raw file content.
    • Response: status code is 200, response body is json in the following format.

          "ok": boolean,
          "entry_added": int,
          "first3entries": [string],
          "lastEntry": string
    • Description: Upload a contact file to server so you can search in them. POST the same file multiple times does no harm, if a line has not changed in contact file, that line will be ignored automatically. You can keep POSTing the same contact file to get updates.
  • POST /api/reset
    • Request: No request parameter required.
    • Response: status code is 200, response body is json {"ok": boolean}
    • Description: Remove all my contacts data on server. Warning: this is not recoverable!

All the above API requires two headers in HTTP request. X-Auth-UserId is the user id and X-Auth-Token is the api token. You will get 403 error if they are not passed or is incorrect. You can get both parameters from the app.

Here is how to call the reset API using curl:

curl -H "X-Auth-UserId: $YOUR_USER_ID" \
     -H "X-Auth-Token: $YOUR_API_TOKEN" \
     -X POST

No warranty

This app is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. The search service is provided in a best effort basis. The author is not responsible for data lose or service down time.


App icon comes from, thanks.

Source code

TODO Source code will be published on GitHub.

Is this post helpful?