{ "openapi": "3.0.1", "info": { "title": "Voucherify API - Locations", "version": "v2018-08-01", "description": "Voucherify promotion engine REST API. Please see https://docs.voucherify.io/docs for more details.", "contact": { "name": "Voucherify Team", "url": "https://www.voucherify.io/contact-support", "email": "support@voucherify.io" }, "termsOfService": "https://www.voucherify.io/legal/subscription-agreement", "license": { "name": "MIT", "url": "https://github.com/voucherifyio/voucherify-js-sdk/blob/main/LICENSE" } }, "servers": [ { "url": "https://{cluster}.voucherify.io", "description": "Base URL", "variables": { "cluster": { "default": "api", "enum": [ "api", "us1.api", "as1.api", "download", "us1.download", "as1.download" ] } } } ], "paths": { "/v1/locations": { "get": { "operationId": "list-locations", "tags": [ "Locations" ], "summary": "List Locations", "description": "Returns a list of your locations.", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "name": "order", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ParameterOrderListLocations" }, "description": "Sorts the results using one of the filtering options, where the dash `-` preceding a sorting option means sorting in a descending order." }, { "name": "filters", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ParameterFiltersListLocations" }, "description": "Filter the locations using one of the available filters.", "style": "deepObject", "explode": true }, { "name": "end_date", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ParameterDate" }, "description": "A filter on the list based on the end date. This will filter out all locations whose end date falls before the specified date and time. A date value must be presented in the ISO 8601 format (`2016-11-16T14:14:31Z` or `2016-11-16`)." } ], "security": [ { "X-App-Id": [], "X-App-Token": [] }, { "X-Voucherify-OAuth": [ "api", "locations" ] } ], "responses": { "200": { "description": "Returns a dictionary that contains an array of locations. Each entry in the array is a separate location object. If no more locations are available, the resulting array will be empty. The result can be narrowed down according to specified (or default) filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationsListResponseBody" }, "examples": { "Example": { "value": { "object": "list", "data_ref": "data", "data": [ { "id": "loc_NoMGXmHO9OUs7iz9mGWpamma", "object": "location", "name": "Belleville", "shape": { "type": "circle", "format": "distance", "distance": { "center": "geo:40.79372699823857,-74.15092132694554", "radius": "1.54 km" } }, "created_at": "2022-07-15T06:04:36.924Z", "updated_at": null }, { "id": "loc_ae2gKWpAFMsuRhyMqGx2FZFF", "object": "location", "name": "New York", "shape": { "type": "polygon", "format": "geojson", "geojson": { "type": "Polygon", "coordinates": [ [ [ -74.016167, 40.703186 ], [ -74.008687, 40.750656 ], [ -73.943597, 40.851838 ], [ -73.928559, 40.845285 ], [ -73.936152, 40.8356 ], [ -73.934298, 40.810015 ], [ -73.92711, 40.795145 ], [ -73.978623, 40.710432 ], [ -74.013201, 40.701619 ], [ -74.016167, 40.703186 ] ] ] } }, "created_at": "2022-07-15T05:37:45.299Z", "updated_at": null }, { "id": "loc_f5HqjVaiq7g9ISlmivpytxSf", "object": "location", "name": "Germany", "shape": { "type": "circle", "format": "distance", "distance": { "center": "geo:51.303908897065064,10.222253628401518", "radius": "192.37 km" } }, "created_at": "2022-07-14T15:51:39.265Z", "updated_at": null }, { "id": "loc_RcYz537sV07e1t5aG5tIH9FD", "object": "location", "name": "Poland", "shape": { "type": "polygon", "format": "geojson", "geojson": { "type": "Polygon", "coordinates": [ [ [ 18.553923, 50.559107 ], [ 18.528805, 51.087437 ], [ 19.591667, 50.832424 ], [ 19.425109, 50.497984 ], [ 19.375814, 50.330652 ], [ 19.398107, 50.111652 ], [ 18.73906, 49.981498 ], [ 18.272477, 50.088707 ], [ 18.553923, 50.559107 ] ] ] } }, "created_at": "2022-07-14T15:21:55.085Z", "updated_at": null } ], "total": 4, "has_more": false } } } } } } } } }, "/v1/locations/{locationId}": { "get": { "operationId": "get-location", "tags": [ "Locations" ], "summary": "Get Location", "description": "Returns a location object.", "parameters": [ { "schema": { "$ref": "#/components/schemas/ParameterLocationId" }, "name": "locationId", "in": "path", "required": true, "description": "The unique location ID." } ], "security": [ { "X-App-Id": [], "X-App-Token": [] }, { "X-Voucherify-OAuth": [ "api", "locations" ] } ], "responses": { "200": { "description": "Returns a location object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationsGetResponseBody" }, "examples": { "Circle Example": { "value": { "id": "loc_NoMGXmHO9OUs7iz9mGWpamma", "object": "location", "name": "Belleville", "shape": { "type": "circle", "format": "distance", "distance": { "center": "geo:40.79372699823857,-74.15092132694554", "radius": "1.54 km" } }, "created_at": "2022-07-15T06:04:36.924Z", "updated_at": null } }, "Polygon Example": { "value": { "id": "loc_RcYz537sV07e1t5aG5tIH9FD", "object": "location", "name": "Poland", "shape": { "type": "polygon", "format": "geojson", "geojson": { "type": "Polygon", "coordinates": [ [ [ 18.553923, 50.559107 ], [ 18.528805, 51.087437 ], [ 19.591667, 50.832424 ], [ 19.425109, 50.497984 ], [ 19.375814, 50.330652 ], [ 19.398107, 50.111652 ], [ 18.73906, 49.981498 ], [ 18.272477, 50.088707 ], [ 18.553923, 50.559107 ] ] ] } }, "created_at": "2022-07-14T15:21:55.085Z", "updated_at": null } } } } } } } } } }, "components": { "parameters": { "limit": { "name": "limit", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ParameterLimit" }, "description": "Limits the number of objects to be returned. The limit can range between 1 and 100 items. If no limit is set, it returns 10 items." } }, "schemas": { "ParameterOrderListLocations": { "type": "string", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at" ] }, "ParameterFiltersListLocations": { "properties": { "name": { "type": "object", "properties": { "conditions": { "$ref": "#/components/schemas/FilterConditionsString" } } }, "created_at": { "description": "Timestamp representing the date and time when the location was created. The value is shown in the ISO 8601 format.", "type": "object", "properties": { "conditions": { "$ref": "#/components/schemas/FilterConditionsDateTime" } } }, "updated_at": { "description": "Timestamp representing the date and time when the location was updated. The value is shown in the ISO 8601 format.", "type": "object", "properties": { "conditions": { "$ref": "#/components/schemas/FilterConditionsDateTime" } } } } }, "ParameterDate": { "type": "string", "example": "2023-12-22T10:13:06.487Z", "format": "date-time" }, "LocationsListResponseBody": { "title": "List Locations Response Body", "type": "object", "description": "Response schema for listing locations using **GET** `v1/locations`.", "properties": { "object": { "type": "string", "description": "The type of the object represented by JSON. This object stores information about locations in a dictionary.", "default": "list" }, "data_ref": { "type": "string", "description": "Identifies the name of the attribute that contains the array of metadata schema objects.", "default": "data" }, "data": { "type": "array", "description": "Array of location objects.", "items": { "$ref": "#/components/schemas/Location" } }, "total": { "type": "integer", "description": "Total number of locations." }, "has_more": { "type": "boolean", "description": "As query results are always limited (by the limit parameter), the `has_more` flag indicates if there are more records for given filter parameters. This lets you know if you can run another request (with a different end date filter) to get more records returned in the results." } } }, "ParameterLocationId": { "type": "string", "example": "loc_NoMGXmHO9OUs7iz9mGWpamma" }, "LocationsGetResponseBody": { "title": "Locations Get Response Body", "description": "Response schema for listing locations using **GET** `/v1/locations/{locationId}`.", "allOf": [ { "$ref": "#/components/schemas/Location" } ] }, "ParameterLimit": { "type": "integer", "maximum": 100, "minimum": 1 }, "FilterConditionsString": { "title": "Filter by conditions", "type": "object", "description": "Data filters used to narrow down the data records to be returned in the result.", "properties": { "$in": { "type": "array", "description": "Array of resource values that should be included in the results (multiple values).", "items": { "type": "string" } }, "$not_in": { "type": "array", "description": "Array of resource values that should be included in the results (multiple values).", "items": { "type": "string" } }, "$is": { "type": "string", "description": "Value is exactly this value (single value)." }, "$is_not": { "type": "string", "description": "Results omit this value (single value)." }, "$has_value": { "type": "string", "description": "Value is NOT null. The value for this parameter is an empty string." }, "$is_unknown": { "type": "string", "description": "Value is null. The value for this parameter is an empty string." }, "$starts_with": { "type": "string", "description": "Value starts with the specified string." }, "$ends_with": { "type": "string", "description": "Value ends with the specified string." }, "$contains": { "type": "string", "description": "Value includes the specified string." }, "$not_contain": { "type": "string", "description": "Value does NOT include the specified string." } } }, "FilterConditionsDateTime": { "title": "Filter by conditions", "type": "object", "description": "Data filters used to narrow down the data records to be returned in the result.", "properties": { "$after": { "type": "string", "description": "Value is after this date. The value for this parameter is shown in the ISO 8601 format.", "format": "date-time", "example": "2024-01-01T00:00:00.000Z" }, "$before": { "type": "string", "description": "Value is before this date. The value for this parameter is shown in the ISO 8601 format.", "format": "date-time", "example": "2024-01-01T00:00:00.000Z" }, "$has_value": { "type": "string", "description": "Value is NOT null. The value for this parameter is an empty string." }, "$is_unknown": { "type": "string", "description": "Value is null. The value for this parameter is an empty string." }, "$more_than": { "type": "integer", "description": "Value is more days ago before the current date and time, e.g. more than `10` days ago." }, "$less_than": { "type": "integer", "description": "Value is less days before the current date and time, e.g. less than `10` days ago." } } }, "Location": { "title": "Location object", "type": "object", "description": "This is an object representing a location.", "properties": { "id": { "type": "string", "description": "Unique location ID, assigned by the Voucherify API.", "example": "loc_NoMGXmHO9OUs7iz9mGWpamma" }, "object": { "type": "string", "description": "The type of the object represented by JSON. This object stores information about a `location`.", "default": "location", "enum": [ "location" ] }, "name": { "type": "string", "description": "Location name." }, "shape": { "type": "object", "description": "Defines the shape and boundaries of the location.", "oneOf": [ { "$ref": "#/components/schemas/LocationShapeCircle" }, { "$ref": "#/components/schemas/LocationShapePolygon" } ] }, "created_at": { "type": "string", "example": "2022-02-14T15:12:06.817Z", "description": "Timestamp representing the date and time when the location was created. The value is shown in the ISO 8601 format.", "format": "date-time" }, "updated_at": { "type": "string", "example": "2022-03-14T15:12:06.817Z", "nullable": true, "description": "Timestamp representing the date and time when the location was updated. The value is shown in the ISO 8601 format.", "format": "date-time" } }, "required": [ "id", "object", "name", "shape", "created_at", "updated_at" ] }, "LocationShapeCircle": { "title": "Circle", "type": "object", "description": "This is an object representing a circular shape.", "properties": { "type": { "type": "string", "description": "The type of shape being defined is a `circle`.", "enum": [ "circle" ] }, "format": { "type": "string", "description": "The location is defined in terms of a `distance` object.", "enum": [ "distance" ] }, "distance": { "type": "object", "title": "Distance", "description": "Defines the parameters for the circle.", "properties": { "center": { "type": "string", "description": "Center of the circle identified by GPS coordinates in decimal degrees.", "example": "geo:40.79372699823857,-74.15092132694554" }, "radius": { "type": "string", "description": "Defines the radius of the circle." } } } }, "required": [ "type", "format", "distance" ] }, "LocationShapePolygon": { "title": "Polygon", "type": "object", "description": "This is an object representing a polygon.", "properties": { "type": { "type": "string", "description": "The type of shape being defined is a `polygon`.", "enum": [ "polygon" ] }, "format": { "type": "string", "description": "The location is defined in terms of a `geojson` object.", "enum": [ "geojson" ] }, "geojson": { "oneOf": [ { "$ref": "#/components/schemas/GeojsonPolygon" }, { "$ref": "#/components/schemas/GeojsonMultiPolygon" } ] } }, "required": [ "type", "format", "geojson" ] }, "GeojsonPolygon": { "type": "object", "title": "Geojson Polygon", "description": "Defines the parameters for the polygon.", "properties": { "type": { "type": "string", "description": "Type of geojson coordinates, i.e. `Polygon`.", "enum": [ "Polygon" ] }, "coordinates": { "$ref": "#/components/schemas/PolygonCoordinates" } }, "required": [ "type", "coordinates" ] }, "GeojsonMultiPolygon": { "type": "object", "title": "Geojson Multi Polygon", "description": "Defines the parameters for the polygon.", "properties": { "type": { "type": "string", "description": "Type of geojson coordinates, i.e. `MultiPolygon`.", "enum": [ "MultiPolygon" ] }, "coordinates": { "type": "array", "items": { "$ref": "#/components/schemas/PolygonCoordinates" } } }, "required": [ "type", "coordinates" ] }, "PolygonCoordinates": { "title": "PolygonCoordinates", "type": "array", "items": { "type": "array", "items": { "type": "integer" } } } }, "securitySchemes": { "X-App-Id": { "type": "apiKey", "name": "X-App-Id", "in": "header" }, "X-App-Token": { "type": "apiKey", "name": "X-App-Token", "in": "header" }, "X-Voucherify-OAuth": { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://api.voucherify.io/v1/oauth/token", "scopes": { "api": "Gives access to whole server-side API.", "vouchers": "Gives access to all endpoints and methods starting with `v1/vouchers`.", "client_api": "Gives access to whole client-side API.", "client_vouchers": "Gives access to all endpoints and methods starting with `/client/v1/vouchers`.", "promotions": "Gives access to all endpoints and methods starting with `/v1/promotions`.", "client_promotions": "Gives access to all endpoints and methods starting with `/client/v1/promotions`", "campaigns": "Gives access to all endpoints and methods starting with `v1/campaigns`.", "client_publish": "Gives access to all endpoints and methods starting with `/client/v1/publish`.", "exports": "Gives access to all endpoints and methods starting with `/v1/exports`.", "publications": "Gives access to all endpoints and methods starting with `/v1/publications`.", "client_validate": "Gives access to all endpoints and methods starting with `/client/v1/validate`.", "validations": "Gives access to all endpoints and methods starting with `/v1/validations`.", "client_validations": "Gives access to all endpoints and methods starting with `/client/v1/validations`.", "qualifications": "Gives access to all endpoints and methods starting with `/v1/qualifications`.", "client_qualifications": "Gives access to all endpoints and methods starting with `/client/v1/qualifications`.", "client_redeem": "Gives access to all endpoints and methods starting with `/client/v1/redeem", "redemptions": "Gives access to all endpoints and methods starting with `/v1/redemptions`.", "client_redemptions": "Gives access to all endpoints and methods starting with `/client/v1/redemptions`", "customers": "Gives access to all endpoints and methods starting with `/v1/customers`.", "client_customers": "Gives access to all endpoints and methods starting with `/client/v1/customers`.", "orders": "Gives access to all endpoints and methods starting with `/v1/orders`.", "products": "Gives access to all endpoints and methods starting with `/v1/products`.", "skus": "Gives access to all endpoints and methods starting with `/v1/SKUs`.", "validation-rules": "Gives access to all endpoints and methods starting with `/v1/validation-rules`.", "validation-rules-assignments": "Gives access to all endpoints and methods starting with `/v1/validation-rules-assignments", "segments": "Gives access to all endpoints and methods starting with `/v1/segments`.", "events": "Gives access to all endpoints and methods starting with `/v1/events`.", "client_events": "Gives access to all endpoints and methods starting with `client/v1/events`.", "rewards": "Gives access to all endpoints and methods starting with `/v1/rewards`.", "assets": "Gives access to all endpoints and methods starting with `/v1/assets`.", "task-results": "Gives access to all endpoints and methods starting with `/v1/task-results`.", "loyalties": "Gives access to all endpoints and methods starting with `/v1/loyalties`.", "client_consents": "Gives access to all endpoints and methods starting with `client/v1/consents`.", "consents": "Gives access to all endpoints and methods starting with `/v1/consents`.", "async-actions": "Gives access to all endpoints and methods starting with `/v1/async-actions`.", "product-collections": "Gives access to all endpoints and methods starting with `/v1/product-collections`.", "categories": "Gives access to all endpoints and methods starting with `/v1/categories`.", "metadata-schemas": "Gives access to all endpoints and methods starting with `/v1/metadata-schemas`.", "locations": "Gives access to all endpoints and methods starting with `/v1/locations`.", "referrals": "Gives access to all endpoints and methods starting with `/v1/referrals`.", "trash-bin": "Gives access to all endpoints and methods starting with `/v1/trash-bin`.", "templates": "Gives access to all endpoints and methods starting with `/v1/templates`." } } } } } } }