Melissa Releases Web Service

Releases Web Service allows users to securely and efficiently download data files, object binaries, and other collateral files from Melissa Data. This service enables users to automate the process of updating their data by allowing them to script the download of specific files rather than downloading the entire zip file. Additionally, file versioning is provided, making it easier to download historical data if necessary.

For example, users are able to download the data files specific for Address Object plus the correct Windows object library and any wrappers required, without needing to download the entire zip archive.

To ensure the security and integrity of the data being downloaded, Releases Web Service requires the user’s subscription license.

CLI Application

Melissa also offers an open-source command-line interface (CLI) for Windows and Ubuntu, available here: Melissa Updater Git. The CLI simplifies the update process by providing a simple interface to consume the Releases web service. Instead of scheduling a custom process, you can schedule simplified console commands

The CLI App, MelissaUpdater, offers simplicity and uses the Releases service to check for updates, download files, and verify the integrity of those files.

After testing, scheduling a batch file or PowerShell script to utilize the CLI tool could automate the process entirely.

To see requirements, source code, and documented usage with examples, see the README at https://github.com/MelissaData/MelissaUpdater.

You can also download the .exe or Linux executable via these links:

• Windows: https://releases.melissadata.net/Download/Library/WINDOWS/NET/ANY/latest/MelissaUpdater.exe
• Linux: https://releases.melissadata.net/Download/Library/LINUX/NET/ANY/latest/MelissaUpdater

Option - Download via Manifests (recommended)

To download an entire manifest with the latest available reference data release, see these examples (using PowerShell syntax):

• Download Data:

  .\MelissaUpdater.exe manifest -l ‘YOUR_MELISSA_LICENSE' -p '*_data' -r 'latest' -t 'C:\PATH\TO\YOUR\DATA’ -d

• Download Binaries:

  .\MelissaUpdater.exe manifest -l ‘YOUR_MELISSA_LICENSE' -p ‘*_bins’ -r 'latest' -t 'C:\PATH\TO\YOUR\BINARIES’ -d

• Note: These commands will download *all* files in each manifest. This method is recommended for simple and less error-prone updates.
• The “-d” (“--dry-run”) option is included here for a “dry run”, to preview actions to be taken.
• The application will check if there is an updated version before performing the download. If the latest is already downloaded to the target directory, no updates are performed.

Option - Download Individual Files *see note below

Alternatively, you could download each file separately.

The simplest way to get an example of the download link structure is to use the Releases Browser.

For example:

1. Navigate here: https://releases.melissadata.net/browse
2. Select your product, enter your License in the “License” input and click “Update”. This will create links in the “FileName” column from which you can start manual downloads.
3. Right-click and “Copy link address” to retrieve the download link for that specific file for the selected “Release”.
1. The link will look like:

   https://releases.melissadata.net/Download/Data/2023.04/{{DATAFILE_NAME}}/?ID={{YOUR_LICENSE}}

2. To always get the latest available update, in the above link you would substitute 2023.04 for latest.
4. The equivalent MelissaUpdater command would be

   .\MelissaUpdater.exe file -l ‘YOUR_MELISSA_LICENSE' -n ‘DATAFILE_NAME’ -r 'latest' -t 'C:\PATH\TO\YOUR\DATA’ -d

1. The “-d” (“--dry-run”) option is included here for a “dry run”, to preview actions to be taken.

*If you choose to download individual files, be wary that this could cause data conflicts – all data files and binaries should be from the same release.

Custom Application

All of the above CLI app operations consume the Releases Web Service; you could also write a custom application to consume this service.

However, the CLI simplifies use of the service greatly, handling file system operations, ensuring the integrity of the downloads, and automatically checking to ensure updates are actually available.

Read on to learn more about how Releases works.

Scripted File Download

Releases Web Service is recommended for scripted file downloads, an efficient method to ensure fresh data and file updates from Melissa.

To get started:

1. Get set up with a Melissa Customer ID. This will be needed to access files.
2. Determine the release and manifest name of the file in which you’d like to download. It is recommended to be included in the script, to ensure the retrieval of the latest files. This can be done by:
   1. Using the Retrieve Releases from Manifest endpoint to determine the desired release.
   2. Using the Retrieve Manifests From Release endpoint to retrieve a list of all manifests associated with a release. To find the latest release, enter in LATEST for the release parameter.
3. After determining the desired release and manifest name, use the Retrieve Files From Manifest endpoint to retrieve REST requests to download files corresponding to the release and manifest name.

OR

1. To find the desired release, architecture, OS, language interface, compiler and filename, go to the Releases Web Browser. You may download the file directly, or for scripted use.
• For data files, use the Download Data File endpoint.
• For a binary file download, use the Download Binary File endpoint.
• For language interface files, use the Download Language Interface File endpoint.

Address Object

To fully update Address Object, we will need to download necessary data files as well any object wrappers/DLLS, if they have been updated. In this use case, we will download the address object binary as well as the address object data file.

1. Determine Release for Desired Manifest

To retrieve the latest data, here we will determine the latest release, utilizing the Retrieve Releases From Manifest endpoint. In this case, we are specifically looking at dq_addr_bins and dq_addr_data.

You may want to schedule a call to this endpoint on a regular basis (e.g. daily) to check for updates.

To access this endpoint, use the following GET requests [view template]

https://releases.melissadata.com/manifestReleases/dq_addr_bins?ID=[CustomerID]&FORMAT=json

Copy to Clipboard

https://releases.melissadata.com/manifestReleases/dq_addr_data?ID=[CustomerID]&FORMAT=json

Copy to Clipboard

Upon successful submission, you will receive a list of releases available for the manifest. The last date listed will be the latest release, and will be used to download the files needed.

Here is an example of the output, in JSON:

[
"2022.10",
"2022.11",
"2022.12"
“2023.01”
]

2. Retrieve Links to Download Files for Target Manifest

After determining the latest release, use the Manifest List endpoint, to retrieve links to download files for the target manifest. Again, we specifically want to update the Address Object in this use case.

To access this endpoint, use the following GET requests [view template]

https://releases.melissadata.com/manifest/2022.12/dq_addr_bins?ID=[ProductLicense&FORMAT=json

Copy to Clipboard

https://releases.melissadata.com/manifest/2022.12/dq_addr_data?ID=[ProductLicense]&FORMAT=json

Copy to Clipboard

You may also use LATEST for the release parameter, to download entire manifests. However, it is not recommended for individual files; there may be conflicts.

Upon successful submission for both endpoints, you will receive a list of download links for Address Object files.

Here is an example of the output in JSON, for dq_addr_bins:

[
  "https://releases.melissadata.net/Download/Library/LINUX/GCC48/64BIT/2022.12/libmdAddr.so/?ID=[ProductLicense]",
  "https://releases.melissadata.net/Download/Library/WINDOWS/DLL/32BIT/2022.12/mdAddr.dll/?ID=[ProductLicense]",
  "https://releases.melissadata.net/Download/Library/WINDOWS/DLL/64BIT/2022.12/mdAddr.dll/?ID=[ProductLicense]
]

The output will include all links to the mdAddr (the address object binary file) download, specified for the architecture, compiler and operating system. View the list of supported systems, architectures, and compilers at the os REST parameter.

For this use case, we need a Address Object download for Windows, on a 64BIT system. The compiler DLL is used for Address Object DLL’s.

For our data file download, here is an example of the JSON response:

[
  "https://releases.melissadata.net/Download/Data/2023.01/ews.txt/?ID=[ProductLicense]",
  "https://releases.melissadata.net/Download/Data/2023.01/lcd256/?ID=[ProductLicense]",
  "https://releases.melissadata.net/Download/Data/2023.01/mdAddr.dat/?ID=[ProductLicense]”
]

Here, we will choose to download mdAddr.dat as our desired data file. However, there are many other files we are able to download. This will depend on whether you need to update all address object data files or just a specific one.

3. Download Address Object File

After retrieving the download links, use the link URL to begin the downloads. Use an appropriate library for your script to handle the file download stream into the installation directory. Consider that this may require administrative privileges for the target directory.

4. Check the File Hash

After downloading the object, it is recommended to check the file hash to verify a successful download.

FOR WINDOWS

For scripted use on Windows, it is recommended to use a library to create and execute system commands.

• C++ and C#: system
• Python: os
• Java: runtime (built-in), process (built-in)

After determining the library needed, use the following command:

certutil -hashfile filename.ext HASH

• Filename.ext should be replaced with the desired file name.
• Here, hash can be replaced with the desired hash format.

For our use case, the command would be:

Certutil -hashfile mdAddr.dll SHA256

For Python, on Windows, using os, this command would look like:

import os

os.system("cd Desktop/FileLocation") # change directory to the file location
os.system("certutil -hashfile filename.ext HASH")

The command should return the file hash, for example: c749b3e0bdfda00043cacb7a1821de79782f21d432ff0eef648f8239e47fa52d.

FOR LINUX

After determining the library needed, use the following command:

Hashtypesum <file_name>

• file_name should be replaced with the desired file name.
• Here, hashtypesum can be replaced with the desired hash format + ‘sum’.

For the address object example, this command would be:

Sha256sum libmdAddr.so

The command should return the file hash, for example: c429e37bdcfb8b49f4f61ca2ffa0fe747030f3cd683122eabaec67a31bc46724.

To verify the locally generated hashes, use the hash value endpoints for your file. Each endpoint is specified for either a data file, language interface file or a binary download. If these hash values match, your download was successful and the files were not corrupted.

For our use case, use the Retrieve Hash Value For Binary File endpoint to check the file hash for mdAddr.dll. The hashType should match the one specified in the command.

https://releases.melissadata.net/SHA256/library/WINDOWS/COM/64BIT/2022.12/AddrObj.dll?ID=[ProductLicense]&Format=JSON

The same steps can be followed for the data file, using the Retrieve Hash Value For Data File endpoint.

The responses should be the same as the file hash returned in the command.

REST Parameters	Description
ID	The License Key issued by Melissa (Encrypted)
release	Release Name. This can be specified in several ways: yyyy.mm OR yyyy-mm (year, month) yyyy.qq (year, quarter) metaReleaseName (For example, latest)
fileName	Name of File
manifest	Manifest Name
os	Describes the target OS. Used for object binaries and language interface binaries: AIX = AIX PowerPC HPUX_IT = HP-UX ia64 HPUX_PA = HP-UX RISC LINUX = Linux Redhat ZLINUX = IBM zLinux SOLARIS = Solaris Sparc WINDOWS = Windows ANY
compiler	Describes the target compiler. ACC3 = HP-UX native compiler COM = Windows COM DLL DLL = Windows standard DLL GCC32 = gcc v3.2 (Linux) GCC34 = gcc v3.4 (AIX, HP-UX, Linux) GCC41 = gcc v4.1 (Linux) GCC46 = gcc v4.6 (zLinux) GCC83 = gcc v8.3 (AIX) WS6 = Solaris native compiler WS12 = Solaris native compiler XLC6 = AIX native compiler XLC12 = AIX native compiler SSIS2005 = SSIS 2005 component SSIS2008 = SSIS 2008 component SSIS2012 = SSIS 2012 component SSIS2014 = SSIS 2014 component SSIS2016 = SSIS 2016 component SSIS2017 = SSIS 2017 component ANY
language	Describes the language interface. NET = .NET C = C/C++ JAVA = Java PERL = Perl PHP = PHP (legacy, prior to v7) PHP7 = PHP v7 PYTHON = Python RUBY = Ruby PLSQL = Oracle PL/SQL MSSQL = SQL Server T-SQL
architecture	Describes the target architecture (ie, ‘bitness’). Used for object binaries and language interface binaries on certain OS platforms: 32BIT 64BIT ANY
format	Desired Format of Response: crLfList = (default) File list delimited by CR/LF lfList = File list delimited by LF comma = comma delimited list tab = tab delimited list json = JSON serialized list xml = XML serialized list
hashType	MD5, SHA1, SHA258

Releases Web Browser

Endpoint

https://releases.melissadata.net/browse?MFT=&RELEASE=&ID=

Copy to Clipboard

Output

After successful submission, you will be redirected to the online browser where you may select different releases and manifests from drop-down boxes. Be sure to include ID.

To access the site directly, use https://releases.melissadata.net/browse.

Direct Download

Download Data File

Endpoint

https://releases.melissadata.net/download/data/:release/:fileName?ID=

Copy to Clipboard

Output

After successful submission, you will be redirected to an automatic file download.

Download Binary File

Endpoint

https://releases.melissadata.net/download/library/:os/:compiler/:architecture/:release/:filename?ID=&Format=

Copy to Clipboard

Output

After successful submission, you will be redirected to an automatic file download.

Download Language Interface File

Endpoint

https://releases.melissadata.net/download/library/:os/:language/:architecture/:release/:filename?ID=

Copy to Clipboard

Output

After successful submission, you will be redirected to an automatic file download.

Retrieve Available Releases

Retrieve Available Releases for Data File

Endpoint

https://releases.melissadata.com/releases/data/:fileName?ID=&FORMAT=

Copy to Clipboard

Output

Example Output (JSON)

[
    "2021.04",
    "2021.05",
    "2021.06",
    "2021.07",
    "2021.08",
    "2021.09",
    "2021.10",
    "2021.11",
    "2021.12",
    "2022.01",
    "2022.02",
    "2022.03",
    "2022.04",
    "2022.05",
    "2022.06",
    "2022.07",
    "2022.08",
    "2022.09",
    "2022.10",
    "2022.11",
    "2022.12"
]

Retrieve Available Releases for Binary File

Endpoint

https://releases.melissadata.com/releases/library/:os/:compiler/:architecture/:fileName?ID=&format=

Copy to Clipboard

Output

Example Output (JSON)

[
    "2021.04",
    "2021.05",
    "2021.06",
    "2021.07",
    "2021.08",
    "2021.09",
    "2021.10",
    "2021.11",
    "2021.12",
    "2022.01",
    "2022.02",
    "2022.03",
    "2022.04",
    "2022.05",
    "2022.06",
    "2022.07",
    "2022.08",
    "2022.09",
    "2022.10",
    "2022.11",
    "2022.12"
]

Retrieve Available Releases for Language Interface File

Endpoint

https://releases.melissadata.com/releases/interface/:os/:language/:architecture/:fileName?ID=&format=

Copy to Clipboard

Output

Example Output (JSON)

[
    "2021.04",
    "2021.05",
    "2021.06",
    "2021.07",
    "2021.08",
    "2021.09",
    "2021.10",
    "2021.11",
    "2021.12",
    "2022.01",
    "2022.02",
    "2022.03",
    "2022.04",
    "2022.05",
    "2022.06",
    "2022.07",
    "2022.08",
    "2022.09",
    "2022.10",
    "2022.11",
    "2022.12"
]

Retrieve Files From Manifest

Endpoint

https://releases.melissadata.com/manifest/:release/:manifest?ID=&format=

Copy to Clipboard

Output

Example Output (JSON)

[
"https://releases.melissadata.net/Download/Library/WINDOWS/COM/64BIT/2022.12/AddrObj.dll/?ID=exampleID1234",
"https://releases.melissadata.net/Download/Library/HPUX_IT/ACC3/32BIT/2022.12/libmdAddr.sl/?ID=exampleID1234"
]

Retrieve Releases From Manifest

Endpoint

https://releases.melissadata.com/manifestReleases/:manifest?ID=&format=

Copy to Clipboard

Output

Example Output (JSON)

[
    "2021.04",
    "2021.05",
    "2021.06",
    "2021.07",
    "2021.08",
    "2021.09",
    "2021.10",
    "2021.11",
    "2021.12",
    "2022.01",
    "2022.02",
    "2022.03",
    "2022.04",
    "2022.05",
    "2022.06",
    "2022.07",
    "2022.08",
    "2022.09",
    "2022.10",
    "2022.11",
    "2022.12"
]

Retrieve Manifests From Release

Endpoint

https://releases.melissadata.com/manifestList/:release?ID=&format=

Copy to Clipboard

Output

Example Output (JSON)

[{"manifestName":"cgd_dvd","description":"Canadian geodata files","url":"https://releases.melissadata.net/Manifest/2022.12/cgd_dvd/?ID=exampleID1234"},
{"manifestName":"dq_addr_bins","description":"DQT\u0027s Address Object binaries","url":"https://releases.melissadata.net/Manifest/2022.12/dq_addr_bins/?ID=exampleID1234"}

Retrieve Metadata

Retrieve Metadata for Data File

Endpoint

https://releases.melissadata.net/metadata/data/:release/:fileName?ID=

Copy to Clipboard

Output

Example Output (JSON)

{
    "FileName": "Congress.csv",
    "Release": "2022.12",
    "BuildDate": "2022-12",
    "FileSize": "45994",
    "MD5": "7d1901fada065fd1b144d3badb5112ce",
    "SHA1": "188f383fe3b822a2225ac53bebe4490f86b097e0",
    "SHA256": "9a945a6148834b9a3792a704898a8627388f6706f7385b847921438d468f8e38"
}

Retrieve Metadata for Binary File

Endpoint

https://releases.melissadata.net/metaData/library/:os/:compiler/:architecture/:release/:filename?ID=&Format=

Copy to Clipboard

Output

Example Output (JSON)

{
    "FileName": "mdGeo.dll",
    "Release": "2022.12",
    "BuildNumber": "4.0.1.17333",
    "FileSize": "1640312",
    "OS": "WINDOWS",
    "Compiler": "DLL",
    "Architecture": "64BIT",
    "MD5": "d8c241620e4f8b6d304b4bb5f06a2808",
    "SHA1": "3c43dabca97b4f8bc800c8e76fe5c8f9fdb4012f",
    "SHA256":    "95652aac77b8daabea60268782157188683f0e31cddbcdca36b954d6a87d0ab1"
}

Retrieve Metadata for Language Interface File

Endpoint

https://releases.melissadata.net/metaData/interface/:os/:language/:architecture/:release/:filename?ID=

Copy to Clipboard

Output

Example Output (JSON)

{
    "FileName": "mdAddr_cSharpCode.cs",
    "Release": "2022.12",
    "FileSize": "99079",
    "Language": "NET",
    "Architecture": "ANY",
    "MD5": "8dda5f69d5e749df45f003524e72607a",
    "SHA1": "a093e92414e6e308b991bfd96a2dab11eefc2bb8",
    "SHA256": "133f6656d1ee9433e8f09f1a948d764743169a1453eaa56fe473dc70daa77ef7"
}

Using Hashes

Retrieve Hash Value for Data File

Endpoint

https://releases.melissadata.net/:hashType/data/:release/:fileName?ID=

Copy to Clipboard

Output

Example Output (JSON)

9a945a6148834b9a3792a704898a8627388f6706f7385b847921438d468f8e38

Retrieve Hash Value for Binary File

Endpoint

https://releases.melissadata.net/:hashType/library/:os/:compiler/:architecture/:release/:filename?ID=&Format=

Copy to Clipboard

Output

Example Output (JSON)

9a945a6148834b9a3792a704898a8627388f6706f7385b847921438d468f8e38

Retrieve Hash Value for Language Interface File

Endpoint

https://releases.melissadata.net/:hashType/interface/:os/:language/:architecture/:release/:filename?ID=

Copy to Clipboard

Output

Example Output (JSON)

9a945a6148834b9a3792a704898a8627388f6706f7385b847921438d468f8e38

To ensure fresh data, it is best to schedule automatic downloads to update application files, including checks for new releases and updates, on a regular basis (e.g. daily).

Use the File Hash Endpoint to ensure the integrity of file downloads.

Hash Verification

It is recommended to script these commands in your language of choice to automatically run these checks after a file download.

FOR WINDOWS

To determine file hash after download,

1. Open Windows Powershell
2. Type Command: certutil -hashfile filename.ext SHA256
1. Filename.ext should be replaced with the desired file name.
2. Here, SHA256 can be replaced with the desired hash format.

After pressing enter, the command will return the file hash. For example, c429e37bdcfb8b49f4f61ca2ffa0fe747030f3cd683122eabaec67a31bc46724.

To compare, use the hash value endpoints for your file. Each endpoint is specified for either a data file, language interface file or a binary download. If these hash values match, your download was successful and the files were not corrupted.

FOR LINUX

To determine file hash after download,

1. Open the Command Line.
2. Type in Command: sha1sum <file_name>
1. file_name should be replaced with the desired file name.
2. Here, sha1sum can be replaced with the desired hash format.

After pressing enter, the command will return the file hash. For example,c429e37bdcfb8b49f4f61ca2ffa0fe747030f3cd683122eabaec67a31bc46724.

To verify the hash, use the hash value endpoints for your file. Each endpoint is specified for either a data file, language interface file or a binary download. If these hash values match, your download was successful and the files were not corrupted.