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
You can access Location Write API here.
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 list accessible using this link.
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
Powered by Azure API Management.