This API lets you create and manage your POIs. You can then perform various analysis on your POIs.

The creation of new POIs consumes credits, however all subsequent analyses on these POIs are free.

To call this API you need an API key provided by Seiki. The API key is provided in every HTTP call in the key header.

Here is an example in Python :

requests.get(
    'https://api.seiki.co/v1/account/credits',
    headers = {'key': MY_API_KEY}
    )

In case of failed authentication, the API returns the following status codes :

• 401 : No API key was provided
• 403 : The provided API key is not authorized to access this API

To use this API, you need credits in order to create new POIs : 1 POI = 1 credit Once a POI is created, you can then access access its data at no cost.

To retrieve your amount of credits, you can call the endpoint /account/credits

In case of insufficient credits, the API returns a status code 402.

For the endpoints that create POIs, the optional boolean parameter dry_run can be provided, which allows you to check authentication and parameters validity at no cost. It also allows you to retrieve what would be the cost of the computation.

Here's the workflow when you create POIs :

• Check authentication
• Check parameters validity
• Compute projected cost : 1 for each POI, except for the free lat/lng (48.8751, 2.3074)
• Check that you have enough credits
• If it's a dry run, stop here
• Consume projected cost
• Perform computation
• Compute real cost : if a POI was already existing (distance < 1 meter), or if the computation could not be performed on a POI, this POI is free
• If real cost is less than the projected cost, refund the difference

The endpoint /poi lets you create a single new POI. This endpoint is synchronous, which means that your client will wait for the API to answer. You can either create a POI by its latitude / longitude, or by its address :

requests.post(
    'https://api.seiki.co/v1/poi',
    headers = { 'key': MY_API_KEY },
    json = { 'lat': 48.8751, 'lng': 2.3074 }
    ).json()

requests.post(
    'https://api.seiki.co/v1/poi',
    headers = { 'key': MY_API_KEY },
    json = { 'address': '178 bd Haussmann Paris' }
    ).json()

The output contains all information on the POI, including the generated POI id and its data.

You can list all your POIs with the following call :

requests.get(
    'https://api.seiki.co/v1/poi',
    headers = { 'key': MY_API_KEY }
    ).json()

You can also filter this list by multiple parameters : id, tag, or location. The filters can also be lists that contain mulitple values. The following call retrieves all POIs with the tag 'MY_SHOPS', which are in the departments 75 and 91

requests.get(
    'https://api.seiki.co/v1/poi',
    headers = { 'key': MY_API_KEY },
    params = { 'tag': 'MY_SHOPS', 'fr_departement': [ '75', '91' ] }
    ).json()

You can create multiple POIs at once, using the asynchronous endpoint /poi/batch. When submitting your inputs, the API immediately returns a batch id. You can then query the API with this batch id, to check the batch processing state, and retrieve the output when done.

Here's an example submitting a new batch :

body = {
    'items': [
        { 'lat': 48.8751, 'lng': 2.3074 },
        { 'address': '178 bd Haussmann' }
    ]}

MY_BATCH_ID = requests.post(
    'https://api.seiki.co/v1/poi/batch',
    headers = { 'key': MY_API_KEY },
    json = body
    ).json()['batch_id']

To retrieve the state and/or output of a batch, you can use the following code :

requests.get(
    'https://api.seiki.co/v1/batch/' + MY_BATCH_ID,
    headers = { 'key': MY_API_KEY }
    )

To wait until a job is done, you can use the following code :

status_code = 202

while status_code == 202:

    time.sleep(5) # Wait 5 seconds
    output = requests.get(
        'https://api.seiki.co/v1/batch/' + MY_BATCH_ID,
        headers = { 'key': MY_API_KEY }
        )
    status_code = output.status_code

print(output.json())

After your POIs are created, you can perform multiple analyses on these POIs, using a single endpoint : /poi/analysis

This call returns all available data on all POIs :

requests.post(
    'https://api.seiki.co/v1/poi/analysis',
    headers = { 'key': MY_API_KEY }
)

You can apply filters on the set of POIs, the same way as when listing POIs (/poi) :

requests.post(
    'https://api.seiki.co/v1/poi/analysis',
    headers = { 'key': MY_API_KEY },
    params = { 'id': MY_POI_ID }
)

You can also choose a subset of returned KPIs :

requests.post(
    'https://api.seiki.co/v1/poi/analysis',
    headers = { 'key': MY_API_KEY },
    params = { 'id': MY_POI_ID, 'kpi': [ 'section', 'traffic.people_in_a_day' ] }
)

You can also filter data itself on several parameters. The following call returns the average total number of male people passing by the POI between 8 and 11 AM, on a working day :

requests.post(
    'https://api.seiki.co/v1/poi/analysis',
    headers = { 'key': MY_API_KEY },
    params = { 'id': MY_POI_ID, 'kpi': [ 'traffic.people_in_a_day.total' ] },
    json = { 'day_type': 'WORKING_DAYS', 'gender': 'MALE', 'hour': [ 8, 9, 10 ] }
)