Overview
DataAnywhere provides software developers with programmatic access to Convergensee data through logical, easy to use APIs. By integrating Convergensee’s centrally managed, up to date, standardized location data, clients increase the value and utility of their own systems.
For example, DataAnywhere can be used to integrate Convergensee data into your own customer portal, or enrich your own internal databases with Convergensee’s curated and cleansed location data.
Features
Secure access using a unique developer-specific API token corresponding to their authorized operations (API calls) and resources (Locations, Accounts, Users, etc.)
A predefined monthly quota of API calls
Email notifications when 80% and 100% of monthly quota is reached
Real-time access to data
TLS Upgrade
In order to maintain high Data Security Standards, TLS 1.0, TLS 1.1 will be deprecated as of October 31, 2022 for Data Anywhere customers. This means you may have to make a few adjustments in your integration. Users of data anywhere need to ensure they are using TLS 1.2 in order to communicate with Data Anywhere services.
TLS provides communications security for the most sensitive personal and financial information, maintaining the latest TLS encryption protocols to keep the cryptographic apparatus at full strength is a fundamental security standard.
Please see the related document to assist with your implementation.
Authentication
In the header of each DataAnywhere API, include the DataAnywhere API token found on your Profile page.
Use Cases
Query Usage
Call the GET /usage API to determine the total number pre-paid API calls associated with your DataAnywhere subscription and how many API calls have already been made.
Create Location *
Go to the Account Read API documentation here:
Call the GET /accounts API, and identify which Account you would like to associate your new Location with. (In most cases you will only have access to a single account and it will be the only one listed).
If you haven't sufficient information to select the appropriate account, call the GET /account API, to get additional Account details.
Go to the Location Write API documentation here:
Call the POST /location API and in the NewLocationData parameter model specify the AccountID of the target account along with the rest of your Location Data Fields.
Read Location
Go to the Account Read API documentation here:
Call the GET /accounts API, and identify the Account associated with the Location you'd like to access.
Go to the Location Read API documentation here:
Call the GET /locations API, passing the target Account's accountID, to get a list of Locations under that Account.
Call the GET /location API, passing the target Location's LocationId, ReferenceCode, or LocationNumber, to display the Location Data Fields for that location.
Update Location
Go to the Account Read API documentation here:
Call the GET /accounts API, and identify the Account associated with the Location you'd like to access.
Go to the Location Write API documentation here:
Call the GET /locations API, passing the target Account's accountID, to get a list of Locations under that Account.
Call the PUT /location API, passing the target Location's LocationID, ReferenceCode, or LocationNumber, along with the rest of your Location Data Fields in the UpdateLocationData parameter.
Store Locator
Go to the Store Locator API documentation here.
Call the GET/stores API, to get a list of stores under the Account associated with the user's subscription. Some filters and sorting can be applied.
Call the GET/stores/{storeId} API, passing the target store id, to get a single store under the Account associated with the user's subscription.
Call the GET/stores/postalcode API, passing the target postal/zip code, to get a list of stores under the Account associated with the user's subscription. Some filters and sorting can be applied.
Call the GET/stores/region API, passing the target province/region/state, to get a list of stores under the Account associated with the user's subscription.
Getting Feedback
Call the GET /Feedback/getreviews API, and identify the Locations locationId, to get a list of reviews for that location. Parameters are:
Page: the page that is being requested
PageSize: Number of items per page
LocationID: The requested locations Id
* The Create Location method access is limited, by customer/Client. The nature of this function allows for the creation of locations. This ability has direct implications to both what is syndicated and the contractual limitations of the location set. For this reason Create functionality is not a default method of the Locations API.
If the purpose of 'Getting Feedback' is to display on a Location Landing page for the purpose of SEO, then we advise that the origin of the feedback to stated on the page as well. Vendors such as Google could penalize the ranking of pages that do not declare the origin of the feedback displayed.
Suggested copy: 'The displayed reviews have been collected directly from customers with verified purchases for applicable products and/or services.'
Data Model Details
LocationList
LocationList is a data container returned by the GET /locations API, containing a page of Location records associated with an Account.
The Continuation Token is used to return successive fixed length pages of Location records (25 records per page). For example, to get all Location records in a LocationList with 70 records, after the initial call, you would have to pass the Continuation Token back two times.
LocationModel
LocationModel is a data container returned by the GET /location API, and is passed as input into the POST /location and PUT /location APIs, containing reference parameters, Locale data, a Location Data Object (Convergensee location data), and a User Data object (customizable array of key-value pairs).
Locale
A Locale is composed of an ISO 639-1 language code and ISO 3166-1 alpha 2 country code (e.g. en-US, en-CA, fr-CA). Follow this link for a complete list of Locale codes.
LocationDataObject
LocationDataObject is a data container in which all objects and data pertaining to the Location are stored.
Hours of Operation
Hours of Operation are represented as pipe line separated list of precisely 7 values, listed from Sunday to Saturday.
Hours for each day are specified as “Closed”, “24Hrs”, or using 12-hour format range (“HH:MMAM-HH:MMPM”).
Example: “Closed|02:00PM-08:00PM|02:00PM-08:00PM|24Hrs|02:00PM-08:00PM|Closed|09:00AM-01:00PM”.
Hours of Operation State (used in HoursOfOperationStructured) object:
Open = 0 - open all day.
Closed = 1 - closed all day.
24Hrs = 2 - open 24 hours.
OpenByAppointment = 3 - requires an appointment in advance (currently not in use).
Business Categories
A CSV file containing a list of valid Categories can be downloaded at this link.
Payment Method Codes
Valid codes indicating which Payment Methods are accepted at the Location
Payment Method Code
American Express A
Cash H
Check J
Debit Card E
Diners Club C
Discover D
Financing F
Invoice I
MasterCard M
PayPal P
Store Card S
Traveler's Check T
Visa V
Language Codes
Valid codes indicating the languages spoken at the Location
Language Code
Albanian sq
Arabic ar
Croatian hr
Chinese zh
Czech cs
Danish da
Dutch nl
English en
French fr
French Creole cpf
German de
Greek el
Hebrew he
Hindi hi
Hungarian hu
Italian it
Japanese ja
Khmer km
Korean ko
Malay ms
Norwegian no
Polish pl
Portuguese pt
Romanian ro
Russian ru
Spanish es
Thai th
Vietnamese vi
Yiddish yi
Language Cultures
Primary Language – Locale mapping listCultureCode
Culture Code
Not_set 0
af_ZA 1
am_ET 2
ar_AE 3
ar_BH 4
ar_DZ 5
ar_EG 6
ar_IQ 7
ar_JO 8
ar_KW 9
ar_LB 10
ar_LY 11
ar_MA 12
arn_CL 13
ar_OM 14
ar_QA 15
ar_SA 16
ar_SY 17
ar_TN 18
ar_YE 19
as_IN 20
az_Cyrl_AZ 21
az_Latn_AZ 22
ba_RU 23
be_BY 24
bg_BG 25
bn_BD 26
bn_IN 27
bo_CN 28
br_FR 29
bs_Cyrl_BA 30
bs_Latn_BA 31
ca_ES 32
co_FR 33
cs_CZ 34
cy_GB 35
da_DK 36
de_AT 37
de_CH 38
de_DE 39
de_LI 40
de_LU 41
dsb_DE 42
dv_MV 43
el_GR 44
en_029 45
en_AU 46
en_BZ 47
en_CA 48
en_GB 49
en_IE 50
en_IN 51
en_JM 52
en_MY 53
en_NZ 54
en_PH 55
en_SG 56
en_TT 57
en_US 58
en_ZA 59
en_ZW 60
es_AR 61
es_BO 62
es_CL 63
es_CO 64
es_CR 65
es_DO 66
es_EC 67
es_ES 68
es_GT 69
es_HN 70
es_MX 71
es_NI 72
es_PA 73
es_PE 74
es_PR 75
es_PY 76
es_SV 77
es_US 78
es_UY 79
es_VE 80
et_EE 81
eu_ES 82
fa_IR 83
fi_FI 84
fil_PH 85
fo_FO 86
fr_BE 87
fr_CA 88
fr_CH 89
fr_FR 90
fr_LU 91
fr_MC 92
fy_NL 93
ga_IE 94
gd_GB 95
gl_ES 96
gsw_FR 97
gu_IN 98
ha_Latn_NG 99
he_IL 100
hi_IN 101
hr_BA 102
hr_HR 103
hsb_DE 104
hu_HU 105
hy_AM 106
id_ID 107
ig_NG 108
ii_CN 109
is_IS 110
it_CH 111
it_IT 112
iu_Cans_CA 113
iu_Latn_CA 114
ja_JP 115
ka_GE 116
kk_KZ 117
kl_GL 118
km_KH 119
kn_IN 120
kok_IN 121
ko_KR 122
ky_KG 123
lb_LU 124
lo_LA 125
lt_LT 126
lv_LV 127
mi_NZ 128
mk_MK 129
ml_IN 130
mn_MN 131
mn_Mong_CN 132
moh_CA 133
mr_IN 134
ms_BN 135
ms_MY 136
mt_MT 137
nb_NO 138
ne_NP 139
nl_BE 140
nl_NL 141
nn_NO 142
nso_ZA 143
oc_FR 144
or_IN 145
pa_IN 146
pl_PL 147
prs_AF 148
ps_AF 149
pt_BR 150
pt_PT 151
qut_GT 152
quz_BO 153
quz_EC 154
quz_PE 155
rm_CH 156
ro_RO 157
ru_RU 158
rw_RW 159
sah_RU 160
sa_IN 161
se_FI 162
se_NO 163
se_SE 164
si_LK 165
sk_SK 166
sl_SI 167
sma_NO 168
sma_SE 169
smj_NO 170
smj_SE 171
smn_FI 172
sms_FI 173
sq_AL 174
sr_Cyrl_BA 175
sr_Cyrl_CS 176
sr_Cyrl_ME 177
sr_Cyrl_RS 178
sr_Latn_BA 179
sr_Latn_CS 180
sr_Latn_ME 181
sr_Latn_RS 182
sv_FI 183
sv_SE 184
sw_KE 185
syr_SY 186
ta_IN 187
te_IN 188
tg_Cyrl_TJ 189
th_TH 190
tk_TM 191
tn_ZA 192
tr_TR 193
tt_RU 194
tzm_Latn_DZ 195
ug_CN 196
uk_UA 197
ur_PK 198
uz_Cyrl_UZ 199
uz_Latn_UZ 200
vi_VN 201
wo_SN 202
xh_ZA 203
yo_NG 204
zh_CN 205
zh_HK 206
zh_MO 207
zh_SG 208
zh_TW 209
zu_ZA 210
AddressObject: CountryCode and Region/PostalCode Validation Details
The AddressObjects’s CountryCode field accepts ISO 3166-1 alpha 2 country code (e.g. US, CA, DE, etc.).
Depending on the AddressObjects’s CountryCode field, the Region and PostalCode field may be required and subject to validation rules. Which countries require these fields, and corresponding validation rules, if applicable, are listed in a CSV file accessible using this link.
Phone Number Format
In the PhoneNumbersObject, phone numbers must be submitted in the international E.164 standard, which are then validated against the ISO 3166-1 alpha-2 country code provided in the AddressObject.
Examples: +14164923214 (Canada), +441234554861 (UK), +33556064216 (France), +493051053283 (Germany)
You can easily swap between local and E.164 standard phone using Google's libphonenumber library:
Customer Reviews Data Model
CustomerReviewsDto is a data container, a list of which is returned by GET /Feedback/getreviews that contains the review left by a customer.
ReviewID: Id of this review
Rating: Float for a rating between 0 and 5 stars.
Comments: Feedback submitted by customer
CustomerName: Name submitted by customer
FeedbackInclusionFlag: If this review was flagged on the TransparenSEE dashboard.
FeedbackSubmittedDate: UTC time when review was submitted by customer in YYYY-MM-DD HH:MM:SS.SSS format
LocationID: GUID of the location that this review was for.
AccountID: GUID of the account