Sites

Create site

This endpoint provisions a new Site resource within a specific namespace. It features automatic address standardization and geocoding: the system accepts a raw address string (inputAddress) and transforms it into a structured address object with precise geospatial coordinates.

HTTP request

Method: POST

URL: https://test.api.gtt.services/apis/v1alpha/namespaces/{namespace}/site

Path parameters

Parameter	Type	Required	Description	Example
namespace	String	Yes	The unique identifier for the tenant or grouping.	2135

Headers

Header	Value	Description
Content-Type	application/json	Required. Indicates the payload format.
Authorization	Bearer <TOKEN>	Required. Standard OAuth 2.0 access token.

Request body

The payload requires standard resource identifiers (kind, version) and a spec object containing the site details.

Field	Type	Required	Description
kind	String	Yes	Resource type classifier. Must be “site”.
version	String	Yes	API version. Must be “v1alpha”.
namespace	String	Yes	Must match the namespace provided in the URL path.
name	String	Yes	Unique user-defined identifier (slug) for this site.
metadata	Object	No	Container for custom tags and labels.
metadata.labels	Map	No	Key-value pairs for external tracking (e.g., Project IDs).
spec	Object	Yes	The technical specifications of the site.
spec.inputAddress	String	Yes	Raw Address. A single string representing the physical location. The API will parse this to generate structured data.
spec.friendly	String	Yes	A human-readable display name for the site.

Response body

The API returns the created resource with additional system-generated fields.

Note: The inputAddress is removed and replaced by a structured address object and geoLocation data.

Field	Type	Description
metadata.dateCreated	Long	Timestamp of creation (Unix Epoch).
metadata.geoLocation	Object	Enrichment. Geospatial data derived from the input address.
metadata.geoLocation.coordinates	Array	[Longitude, Latitude] pair.
metadata.geoLocation.plusCode	String	The Google Open Location Code (Plus Code) for the site.
spec.address	Object	Enrichment. The parsed, structured version of the inputAddress.
spec.address.line1	String	Street address line 1.
spec.address.city	String	City name.
spec.address.state	String	State or province code.
spec.address.zipcode	String	Postal code.
spec.address.latitude	Float	Precise latitude of the address.
spec.address.longitude	Float	Precise longitude of the address.

Example

Request

The user sends a raw address string (2015 2nd ave...).

{
    "kind": "site",
    "version": "v1alpha",
    "namespace": "2135",
    "name": "intl-test-001",
    "metadata": {
        "labels": {
            "project": "MR-PROJ-1000-A"
        }
    },
    "spec": {
        "inputAddress" : "2015 2nd ave seattle wa 98121",
        "friendly": "Seattle Branch"
    }
}

Response

The system validates the address and returns the structured data.

{
    "kind": "site",
    "version": "v1alpha",
    "namespace": "2135",
    "name": "intl-test-001",
    "metadata": {
        "dateCreated": 1764966214549,
        "dateUpdated": 1764966215838,
        "labels": {
            "project-id": "MR-PROJ-1000-A"
        },
        "geoLocation": {
            "type": "Point",
            "coordinates": [ -122.3424101, 47.6117607 ],
            "plusCode": "84VVJM65+P24"
        }
    },
    "spec": {
        "address": {
            "line1": "2015 2nd Ave",
            "line2": null,
            "city": "Seattle",
            "state": "WA",
            "zipcode": "98121",
            "country": "USA",
            "latitude": 47.61176,
            "longitude": -122.34241,
            "streetNumber": "2015",
            "routeShort": "2nd Ave"
        },
        "friendly": "Seattle Branch"
    }
}

Get site details

Retrieves the configuration, metadata, and geospatial data for a specific site.

HTTP request

GET https://test.api.gtt.services/apis/v1alpha/namespaces/{namespaceId}/site/{name}

Path parameters

Parameter	Type	Required	Description
namespaceId	string	Yes	The unique identifier for the customer or organizational namespace (e.g., 2135).
name	string	Yes	The name or ID of the specific site to retrieve (e.g., intl-test-001).

Headers

Header	Value	Required	Description
Authorization	Bearer <TOKEN>	Yes	Valid OAuth2 bearer token.

Response schema

The response returns a Site object containing the resource’s identity, metadata, and specification.

Top-level attributes

• kind (string): The resource type (always site).
• version (string): The API version (e.g., v1alpha).
• namespace (string): The namespace ID linked to this site.
• name (string): The unique name of the site.

Metadata (metadata)

This object contains system-generated timestamps and user-defined identifiers.

• **dateCreated / dateUpdated** (long): Epoch timestamps representing the site lifecycle.
• labels (object): Dictionary of key-value pairs used for internal tracking (e.g., project, att-id).
• geoLocation (object):
• type: Geometry type (typically Point).
• coordinates: An array containing [longitude, latitude].
• plusCode: The Google Plus Code for high-accuracy location sharing.

Specification (spec)

Defines the physical and operational characteristics of the site.

Address Object

Field	Description
line1	Primary street address.
city / state / zipcode	Standard US address components.
country	ISO 3166-1 alpha-3 country code (e.g., USA).
streetNumber	Extracted building number.
routeLong / routeShort	Full and abbreviated street names (e.g., “2nd Avenue” vs “2nd Ave”).
uk* fields	Regional fields specific to UK addresses (e.g., ukExchangeCode). These are null for non-UK sites.

Quotes Object (quotes)

An optional collection of quote references associated with this site.

• offers (array): A list of objects containing kind, version, namespace, and name pointing to specific quote resources.

Example response

{
    "kind": "site",
    "version": "v1alpha",
    "namespace": "2135",
    "name": "intl-test-001",
    "metadata": {
        "dateCreated": 1764966214549,
        "dateUpdated": 1764966215838,
        "labels": {
            "att-id": "EXT-123456",
            "project": "MR-PROJ-1000-A"
        },
        "geoLocation": {
            "type": "Point",
            "coordinates": [-122.3424101, 47.6117607],
            "plusCode": "84VVJM65+P24"
        }
    },
    "spec": {
        "address": {
            "line1": "2015 2nd Ave",
            "city": "Seattle",
            "state": "WA",
            "zipcode": "98121",
            "country": "USA",
            "latitude": 47.61176,
            "longitude": -122.34241,
            "streetNumber": "2015",
            "routeLong": "2nd Avenue",
            "routeShort": "2nd Ave"
        },
        "friendly": "Seattle Branch",
        "quotes": {
            "offers": [
                {
                    "kind": "quote",
                    "version": "v1alpha",
                    "namespace": "2135",
                    "name": "intl-test-001"
                }
            ]
        }
    }
}