Smarty
0
Cart Icon
Cart
Technical Requirementssidebar-nav-dropdown-icon

Technical Requirements

This page describes the technical requirements for using our services. You are responsible for understanding them. Don't just assume that you know this stuff because you've been programming for years. (Yes, it will be on the test.)

Failure to meet these minimum requirements will result in connectivity issues and service interruptions which are not covered under any Service Level Agreement we offer.

On This Page:

Use DNS to Resolve IP Addresses

Don't hard-code IP addresses—either in code or in your configuration. Our services are geo-distributed and the IP addresses of our servers will change regularly and without notice according to changing and unpredictable network traffic patterns. If you require static IPs due to regulatory compliance, we have an Enterprise plan available.

Resolve DNS According to Published TTLs

Some network-layer software (we see it most commonly with the JVM) by default bypasses DNS-provided time-to-live (TTL) value by indefinitely caching DNS lookups. This is effectively the same as hard-coding IP addresses, as described above. Ensure that your software stack is correctly resolving DNS on a regular basis to avoid unexpected outages.

Trusted Certificate Authorities

Here is the list of trusted certificate authorities with their respective SHA256 Fingerprints:

Expect Our SSL Certificates to Change

Do not hard-code our SSL certificates. In the case of OpenSSL vulnerabilities, certificate authority compromise, or other exploits, our certificates may need to be quickly replaced. (Remember Heartbleed?) Our certificates are rotated before their expiration dates and we may change issuers at any time. We always select an issuer from the major brands as found in the Mozilla Trust Store list. We also rotate our various certificate private keys as an internal best practice.

Use Modern Security Software, Cipher Suites, and Cryptographic Protocols

Supported protocols: TLS 1.2, TLS 1.3

Supported cipher suites:

  • ECDHE-ECDSA-AES256-GCM-SHA384
  • ECDHE-RSA-AES256-GCM-SHA384
  • ECDHE-ECDSA-AES128-GCM-SHA256
  • ECDHE-RSA-AES128-GCM-SHA256
  • ECDHE-ECDSA-CHACHA20-POLY1305
  • ECDHE-RSA-CHACHA20-POLY1305
  • DHE-RSA-AES256-GCM-SHA384
  • DHE-RSA-AES128-GCM-SHA256
  • ECDHE-RSA-AES256-SHA384
  • ECDHE-RSA-AES128-SHA256
  • AES256-GCM-SHA384
  • AES128-GCM-SHA256
  • AES256-SHA256
  • AES128-SHA256
  • ECDHE-RSA-AES256-SHA
  • ECDHE-RSA-AES128-SHA
  • AES256-SHA
  • AES128-SHA

According to the Mozilla SSL Configurator Generator, the above configuration is properly supported by the following frameworks and browsers:

  • Android 4.4.2
  • Java 8u31
  • OpenSSL 1.0.1
  • Firefox 27
  • Chrome 31
  • Edge
  • IE 11 on Windows 7
  • Safari 9
  • Opera 20

We reserve the right to remove support for compromised or cryptographically weak encryption ciphers at any time. Customers connecting to our servers must be able to support modern ciphers. Keep all security software updated and patched, especially after critical vulnerabilities are announced. We may change what SSL/TLS protocol versions and encryption ciphers are utilized according to recently published security exploits such as BEAST, CRIME, and POODLE, among others. Please contact us if you have security-related concerns or visit SSL Labs for a thorough discussion of these matters.

Over time, the relative strength of a given certificate component will have to be increased to avoid changes in computing and cryptography. For example, the respective private keys for our various certificates are currently at least 2048 bits long. This may be increased to 4096 bits in the near future as dictated by security best practices. Furthermore, the relative strength of a given cipher, DHE for example, may need to be increased from 2048 to a larger value. Lastly the hashing function that verifies a certificate may change from SHA2 to another hashing function such as SHA3. As long as your client library and operating system are updated and supported, there shouldn't be any trouble.

Add Technical/Operations Contacts to Your Account

Please keep your contact information current and correct. We can't stress this enough. It will be used only for account-related business, including important technical and billing notifications. We don't use this to spam you, and we don't sell or share the information.

Ensure that there are current email addresses and phone numbers for administrative, billing, and technical personnel in your organization.

Read and Follow our Documentation

We really do know our system better than you do. We go to great efforts to make our documentation correct. Naming and character casing matter. For example, an input of ZIP_Code is not the same as zipcode. Further, make sure to stay true to specified data types. A string is not the same as an integer is not the same as a boolean; for example, the zipcode field is encoded as a string, not an integer. Incorrect naming, casing, or field type will cause the request to be rejected or ignored. Just because the request happens to have been accepted in the past does not mean that it will be accepted in the future.

Follow the HTTP methods or verbs according to the documentation. If our documentation specifies a GET request, don't use another verb. Furthermore, don't match HTTP verbs with incompatible payloads. For example, don't submit a HTTP body with a GET request—use a POST instead, as indicated in the documentation. We cannot guarantee stability of implicit or inferred behavior. Just because it worked before, doesn't mean it will continue unless it is explicitly specified in the documentation.

Comply with HTTP, URI, XML, and JSON Specifications

When sending or receiving data from our service, you will be using HTTP and URIs, and will often be using JSON and/or XML.

Your software must send our service well-formed payloads; no exceptions. We reserve the right to deny HTTP requests to our service which are not fully compliant according to strict specifications, even if such requests may have worked previously. Any such outages caused by non-compliant request payloads are not covered under any service level agreement we offer.

Use properly formed URIs and query strings, which includes URL-encoding query string parameters. Interpret all HTTP response payloads according to their Content-Type. For example, application/json payloads should always be parsed as JSON—don't merely do a string comparison or attempt parsing the response yourself. Be sure to specify Content-Type and Accept in your request headers to be explicit about what you're providing to us and what kind of response you would like. Use well-established, robust serialization/deserialization libraries for your technology stack.

When dealing with JSON payloads, your software should be fully compliant with the JSON specification according to ECMA-404. Our API produces valid JSON according to this standard, including whitespace between tokens. We are not responsible for problems resulting from handling JSON data improperly. Similar principles apply for XML.

With any serialization format (including URI query strings), understand that we will add fields to the response from time to time. Your code should be able to support the addition of data/fields in our response without breaking; that is one of the benefits of the JSON interchange format. For example, suppose your code was written to handle a response from our API that looked like this: 

{
	"city": "Miami",
	"state": "Florida"
}

If a new field was added later, your application should be able to handle it with no problems: 

{
	"city": "Miami",
	"state_abbreviation": "FL",
	"state": "Florida"
}

Similarly, fields with null, empty, false, or zero values may not be serialized into the response at all to save bandwidth and processing power. As such, your code should be able to handle missing fields as much as new fields.

Ideally, your code would be accessing values through their keys, not position or offset. In the case of arrays, anticipate more or fewer array elements unless the contract specifically says otherwise.

Use Modern Browsers

Our site supports all major, modern desktop web browsers including Chrome, Firefox, Safari, Edge, and Opera. Old browsers render content poorly, do not support the latest web standards or technologies, and have known security vulnerabilities. Be sure to enable your browser's automatic update capabilities. We will eventually drop support for old browsers from time to time, even if we currently support them now. For example, just because we support a certain version of Internet Explorer now doesn't mean we will later. We may also need time to make our website compatible with new browsers. Browser support may change without notice.

Retry Requests

HTTP is a stateless, unreliable protocol built atop TCP with no delivery guarantees. Clients accessing our API should build in a retry mechanism in case packets are dropped or connectivity is interrupted due to circumstances and changing network conditions beyond our control.

DNS will provide multiple IP addresses to our API. If any one IP address becomes unresponsive, have your client software reacquire via DNS and temporarily target a different IP while excluding the one that is unresponsive.

Use Secure Endpoints and Don't Ignore Security Warnings

Connect to our API securely (use HTTPS/TLS) and avoid using any plaintext endpoint. Do not ignore security warnings presented by your browser or your code libraries. Ignoring or disabling warnings may indicate TLS protocol version or cipher incompatibilities that must be resolved.

Stay In The Loop

We may use social media, emails, blog posts, web pages, and sometimes phone calls to announce widespread operational changes. Follow us on our various channels to stay informed. To subscribe to updates, simply go to our Status Page and click on "SUBSCRIBE TO UPDATES."

Character Set UTF-8

First thou shalt indicate UTF. Then thou must count to eight. Eight shall be the number of the counting and the number of the counting shall be eight. Nine shalt thou not count, neither shalt thou count seven, excepting that thou then proceedeth to eight. Ten is right out. Once the number eight, being the number of the counting, be reached, then lobbest thou...

Just be happy and use UTF-8. That is all.

For What It's Worth

The requirements on this page are not specific to Smarty (formerly SmartyStreets). Most customers will have no problems by following basic best practices. By rigorously following these principles, we're confident you will have a positive experience using our service. Please don't hesitate to contact us if you have further questions. We're happy to help!

The leader in location data intelligence

Ready to get started?
see pricingexplore the docs