API Authentication

Account Credentials

Your API authentication credentials consist of 2 parts in the exact order as listed:

[ username, password ]

You should have been assigned a username and password when you signed up for a new account with CITYDATA. If you do not know your account credentials, please contact us at support@lotadata.com. If you do not yet have an account, please sign up for an account with CITYDATA.

Now prepare your account credentials as indicated below by joining the first and second part of the credentials using a colon and encoding the resulting string to create your encoded auth credentials.

creds = ':'.join([username, password])
auth = 'Basic ' + b64encode(creds)

[warning] Requirement

The encoded auth credential payload must be 'utf-8'

Session Login Request

The next step is to make a http GET request. You will need to set the encoded auth credentials in the http authorization header, like below.

Authorization header : {'Authorization': auth}
GET https://api2.lotadata.com/v2/session/login
{'@id': 'c989eb2212544.....',
'@type': 'Session',
'expireInMinutes': 60}
where @id is the API key for the current session.

[warning] Warning

Do not use slash at the end of the above GET request URI

Session API Key

Your API key is essential for making API calls to fetch raw data and/or inferences in your current session. You can check if your API key is valid by checking the remaining time in the session, like below.

GET https://api2.lotadata.com/v2/session/remaining?api_key=c989eb2212544....
{'@id': '898252a730034c36a4211d1969b4a5d6',
'@type': 'Session',
'accountType': 'mobile_moments',
'customerType': ['app_developer'],
'email': 'your_email_address',
'expireInMinutes': 29,
'firstName': 'your_first_name',
'orgName': 'your_last_name',
'role': 'admin'
'buckets': [
{'@id': '1409888999999',
'description': 'bucket_description',
'name': 'bucket_name',
'uiType': 'SDK'},
{'@id': '1409688899999',
'description': 'bucket_description',
'name': 'bucket_name',
'uiType': 'SDK'},
{'@id': '1409388899999',
'description': 'bucket_description',
'name': 'bucket_name',
'uiType': 'SDK'},
'canExchange': False,
'companyLogoPath': 'https://s3-us-west-2.amazonaws.com/platform.lotadata.com/beta/content/images/_samples/your_logo.png'
where expireInMinutes is the leftover-time or remaining time in minutes for the current session.

If your session has expired, you can always start a new session with a new API key by initiating a new GET request with the encoded auth credentials in the http authorization header.

Bucket IDs

You will also notice that the login response has one or more bucket IDs. The buckets array represents the datasets or buckets that your accounts has access to. To proceed with making API calls, you will need to use a combination of your session API key and a bucket ID.


We are eager to hear from you and happy to share best practices for integrating the SDK. There are many ways for you to reach us:

But first, please sign up for an account and download our SDK.