Getting Started

## Introduction This guide is intended primarily for developers. It is a supplement to our [technical documentation](, which should be consulted for more detailed information on all endpoints. ## Major and Minor Versions Versions are named as follows: MAJOR.MINOR Examples: v2.0 - major version 2, minor version 0 v2.1 - major version 2, minor version 1 Features will not be removed in minor versions except when required for legal or security reasons. This means that minor versions will be backwards-compatible with their corresponding major versions. Minor versions may include: - New features (parameters and output values). - Fields that may be marked as deprecated. These fields will be removed in the next major version. ## Authentication The Demand API uses HTTP Basic Authentication. For more details, please refer to this [Wikipedia article]( ## Sample URLs General syntax: https://[domain]/[version]</[xml or json]>/[endpoint]?[parameters] JSON and XML examples for v2.0: - GET - GET The default output format is JSON. XML output can be obtained adding `/xml` to the URL, or by passing the HTTP header `Accept: text/xml` Our [technical documentation]( contains JSON URL samples for every endpoint. ## Output format **JSON example** ``` { "result": [ ], "errors": [ { "code": 1000, "message": "Sample error message" } ], "warnings": [ { "code": 1001, "message": "Sample warning message" } ], "request_params": { } } ``` ** XML example ** ``` <EndpointName> <result></result> <result></result> <errors> <code>1000</code> <message>Sample error message</message> </errors> <warnings> <code>1001</code> <message>Sample warning message</message> </warnings> <request_params></request_params> </EndpointName> ``` **Note:** To generate request_params (requested parameters) in the output, the input parameter **show_request_params=1** needs to be added in the request. This can be useful for debugging. ## Pagination The **offset** and **rows** input parameters are used for pagination. The **offset** input parameter specifies where in the resulting list to start pagination. The **rows** parameter specifies the maximum number of entries to return. ## Usage Examples: Retrieve the first 100 entries: **cities?offset=0&rows=100** Retrieve the next 100 entries starting from the 100th row: **cities?offset=100&rows=100** ## Limitations Requests made to the API cannot exceed 8192 characters. In the event of a violation, user will receive a HTTP 403 error response. HTTP GET requests may not contain a request body. In the event of a violatoin, user will receive a HTTP 403 error response.