{ "openapi": "3.0.1", "info": { "title": "Geocoding", "description": "With the Geocoding service you can find locations by converting street addresses into GPS-coordinates and vice versa. The Places service allows to search for millions of shops and prominent points of interest in various categories.", "version": "1.18", "contact": { "url": "https://developer.myptv.com/" } }, "tags": [ { "name": "Locations" }, { "name": "Places" }, { "name": "Categories" }, { "name": "Feedback" } ], "paths": { "/locations/by-text": { "get": { "tags": [ "Locations" ], "description": "Searches for locations based on a single-field text input.", "operationId": "searchLocationsByText", "parameters": [ { "name": "searchText", "in": "query", "description": "Free-form text input that describes a location.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CountryFilterParameter" }, { "$ref": "#/components/parameters/LanguageParameter" }, { "$ref": "#/components/parameters/ResultsParameter" }, { "$ref": "#/components/parameters/CleanInputParameter" } ], "responses": { "200": { "description": "Response on success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationsSearchResult" } } } }, "default": { "description": "Response on failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/locations/by-address": { "get": { "tags": [ "Locations" ], "description": "Searches for locations based on a multi-field address input.", "operationId": "searchLocationsByAddress", "parameters": [ { "name": "country", "in": "query", "description": "The country in which the locations should be searched. A country may be defined by name, ISO code (ISO 3166-1 alpha-2 or alpha-3) or country code plate.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "A subdivision of a country, for example a state, a region or a province. Using this field narrows down the search and reduces the number of possible results.", "schema": { "type": "string" } }, { "name": "locality", "in": "query", "description": "The locality of the address, which may be a city, a district or subdistrict.", "schema": { "type": "string" } }, { "name": "postalCode", "in": "query", "description": "The postal code, or zip-code, which is used by a postal authority of a country to identify where the address is located.", "schema": { "type": "string" } }, { "name": "street", "in": "query", "description": "The name of the road where the address is located. It must not contain additional information like building names, floor numbers or apartment numbers. It may contain a house number, but using the **houseNumber** field instead will lead to better results.", "schema": { "type": "string" } }, { "name": "houseNumber", "in": "query", "description": "The house number of the address.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CountryFilterParameter" }, { "$ref": "#/components/parameters/LanguageParameter" }, { "$ref": "#/components/parameters/ResultsParameter" }, { "$ref": "#/components/parameters/TotalScoreTypeParameter" } ], "responses": { "200": { "description": "Response on success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationsSearchResult" } } } }, "default": { "description": "Response on failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/suggestions/by-address": { "get": { "tags": [ "Locations" ], "description": "Gets suggestions for the address input of the searchLocationsByAddress endpoint.", "operationId": "getSuggestionsByAddress", "parameters": [ { "name": "country", "in": "query", "description": "The country or its initial characters to which the suggestion search is limited. A country may be defined by name, ISO code (ISO 3166-1 alpha-2 or alpha-3) or country code plate.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "The state or its initial characters to which the suggestion search is limited. A state is a subdivision of a country, for example a real state, a region or a province.", "schema": { "type": "string" } }, { "name": "locality", "in": "query", "description": "The locality or its initial characters to which the suggestion search is limited. The locality may be a city, a district or subdistrict.", "schema": { "type": "string" } }, { "name": "postalCode", "in": "query", "description": "The postal code or zip-code or its initial characters to which the suggestion search is limited.", "schema": { "type": "string" } }, { "name": "street", "in": "query", "description": "The name of the road or its initial characters to which the suggestion search is limited. It must not contain additional information like building names, floor numbers or apartment numbers.", "schema": { "type": "string" } }, { "name": "houseNumber", "in": "query", "description": "The house number or its initial characters to which the suggestion search is limited. If only a space is given, a list of all house numbers in the specified street will be suggested. Suggestions for house numbers are only provided if a street is specified.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/InputFieldParameter" }, { "$ref": "#/components/parameters/LanguageParameter" } ], "responses": { "200": { "description": "Response on success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestionsByAddressResponse" } } } }, "default": { "description": "Response on failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/suggestions/by-text": { "get": { "tags": [ "Locations" ], "description": "Gets suggestions for the input of the searchLocationsByText endpoint.\n\nThis method is in a preview state. It is stable, but feature changes could be introduced in the future.", "operationId": "getSuggestionsByText", "parameters": [ { "name": "searchText", "in": "query", "description": "Free-form text input that partially describes a location.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CountryFilterParameter" }, { "$ref": "#/components/parameters/CenterParameter" }, { "$ref": "#/components/parameters/LanguageParameter" } ], "responses": { "200": { "description": "Response on success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestionsByTextResponse" } } } }, "default": { "description": "Response on failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/locations/by-position/{latitude}/{longitude}": { "get": { "tags": [ "Locations" ], "description": "Searches for locations near a given geographical position.", "operationId": "searchLocationsByPosition", "parameters": [ { "$ref": "#/components/parameters/LatitudeParameter" }, { "$ref": "#/components/parameters/LongitudeParameter" }, { "$ref": "#/components/parameters/LanguageParameter" }, { "$ref": "#/components/parameters/MinimumPopulationParameter" } ], "responses": { "200": { "description": "Response on success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationsSearchResult" } } } }, "default": { "description": "Response on failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/feedback": { "post": { "tags": [ "Feedback" ], "description": "Provides feedback about which location or place was considered to be the best match in an array obtained for the corresponding input address, position, or text. This is a fire and forget operation. \n \n This endpoint is experimental and may change at any time in the future.", "operationId": "provideFeedback", "parameters": [ { "$ref": "#/components/parameters/FeedbackIdParameter" } ], "responses": { "204": { "description": "No content." }, "default": { "description": "Response on failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/places/by-text": { "get": { "tags": [ "Places" ], "description": "Searches for places based on a single-field text input.", "operationId": "searchPlacesByText", "parameters": [ { "name": "searchText", "in": "query", "description": "Free-form text input that describes a place.", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CategoryFilterParameter" }, { "$ref": "#/components/parameters/CountryFilterParameter" }, { "$ref": "#/components/parameters/LanguageParameter" }, { "$ref": "#/components/parameters/CenterFilterParameter" }, { "$ref": "#/components/parameters/RadiusParameter" }, { "$ref": "#/components/parameters/BoundingBoxParameter" } ], "responses": { "200": { "description": "Response on success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlacesSearchResult" } } } }, "default": { "description": "Response on failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/places/by-position/{latitude}/{longitude}": { "get": { "tags": [ "Places" ], "description": "Searches for places near a given geographical position.", "operationId": "searchPlacesByPosition", "parameters": [ { "$ref": "#/components/parameters/LatitudeParameter" }, { "$ref": "#/components/parameters/LongitudeParameter" }, { "$ref": "#/components/parameters/RadiusParameter" }, { "$ref": "#/components/parameters/CategoryFilterParameter" }, { "$ref": "#/components/parameters/LimitParameter" }, { "$ref": "#/components/parameters/LanguageParameter" } ], "responses": { "200": { "description": "Response on success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlacesSearchResult" } } } }, "default": { "description": "Response on failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/place-categories": { "get": { "tags": [ "Categories" ], "description": "Returns the list of place categories.", "operationId": "getPlaceCategories", "responses": { "200": { "description": "Response on success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceCategories" } } } }, "default": { "description": "Response on failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/places/by-area": { "post": { "tags": [ "Places" ], "description": "Searches for places within a requested area.", "operationId": "searchPlacesByArea", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlacesByAreaRequest" } } }, "required": true }, "parameters": [ { "$ref": "#/components/parameters/CategoryFilterParameter" }, { "$ref": "#/components/parameters/LanguageParameter" } ], "responses": { "200": { "description": "Response on success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlacesSearchResult" } } } }, "default": { "description": "Response on failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "PlacesByAreaRequest": { "type": "object", "required": [ "area" ], "properties": { "area": { "$ref": "#/components/schemas/Area" } } }, "Area": { "type": "object", "required": [ "geometry" ], "properties": { "geometry": { "type": "string", "description": "The geometry of the area as a [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946) representation (WGS84/EPSG:4326)." } }, "description": "Defines the area as [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946) geometry. Supported geometry types are Polygon and MultiPolygon. Geometries that cause too long processing times will be rejected. In this case an error response is returned that explains the reason." }, "Latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "The latitude value in degrees (WGS84/EPSG:4326) from south to north.", "format": "double" }, "Longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "The longitude value in degrees (WGS84/EPSG:4326) from west to east.", "format": "double" }, "ReferencePosition": { "type": "object", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "$ref": "#/components/schemas/Latitude" }, "longitude": { "$ref": "#/components/schemas/Longitude" } }, "description": "The actual position of the object itself, such as the rooftop of a building, the center of a street, or the reference position of a city." }, "RoadAccessPosition": { "type": "object", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "$ref": "#/components/schemas/Latitude" }, "longitude": { "$ref": "#/components/schemas/Longitude" } }, "description": "A position on or very close to a road that marks the entry to the object. Available only for objects which represent buildings with a complete address and only if present in the data. \n The road from which the object can be accessed is not necessarily the road which is closest to the object." }, "PlacesSearchResult": { "description": "The result of a places search.", "type": "object", "properties": { "places": { "description": "The places which where found.", "type": "array", "items": { "$ref": "#/components/schemas/Place" } }, "noMatchFeedbackId": { "$ref": "#/components/schemas/FeedbackId" }, "warnings": { "description": "A list of warnings concerning the validity of the result.", "type": "array", "items": { "$ref": "#/components/schemas/Warning" } } } }, "Place": { "allOf": [ { "$ref": "#/components/schemas/LocationProperties" }, { "required": [ "categoryIds", "quality" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name of the place." }, "categoryIds": { "type": "array", "description": "An array of place category IDs representing the categories this place is assigned to.", "items": { "type": "string" } }, "quality": { "$ref": "#/components/schemas/Quality" } } } ] }, "LocationsSearchResult": { "description": "The result of a locations search.", "type": "object", "required": [ "locations" ], "properties": { "locations": { "type": "array", "description": "The found locations.", "items": { "$ref": "#/components/schemas/Location" } }, "noMatchFeedbackId": { "$ref": "#/components/schemas/FeedbackId" }, "warnings": { "description": "A list of warnings concerning the validity of the result.", "type": "array", "items": { "$ref": "#/components/schemas/Warning" } } } }, "Location": { "allOf": [ { "$ref": "#/components/schemas/LocationProperties" }, { "required": [ "quality", "locationType" ], "type": "object", "properties": { "locationType": { "$ref": "#/components/schemas/LocationType" }, "quality": { "$ref": "#/components/schemas/Quality" } } } ] }, "SuggestionsByAddressResponse": { "description": "The list of suggested addresses.", "type": "object", "required": [ "suggestions" ], "properties": { "suggestions": { "type": "array", "description": "The list of suggested addresses.", "items": { "$ref": "#/components/schemas/SuggestedAddress" } }, "warnings": { "description": "A list of warnings concerning the validity of the result.", "type": "array", "items": { "$ref": "#/components/schemas/Warning" } } } }, "SuggestedAddress": { "description": "An address suggested for the input of the searchLocationsByAddress endpoint.", "type": "object", "required": [ "caption" ], "properties": { "caption": { "type": "string", "description": "A summary of this suggestion that can be displayed on a user interface." }, "country": { "type": "string", "description": "The country of the suggested address or the provided input." }, "state": { "type": "string", "description": "The state/province of the suggested address or the provided input." }, "postalCode": { "type": "string", "description": "The postal code or zip code of the suggested address or the provided input." }, "locality": { "type": "string", "description": "The locality of the suggested address or the provided input." }, "street": { "type": "string", "description": "The street of the suggested address or the provided input." }, "houseNumber": { "type": "string", "description": "The house number of the suggested address or the provided input." } } }, "SuggestionsByTextResponse": { "description": "The list of suggestions for the search text.", "type": "object", "required": [ "suggestions" ], "properties": { "suggestions": { "type": "array", "description": "The list of suggested search texts.", "items": { "$ref": "#/components/schemas/Suggestion" } }, "warnings": { "description": "A list of warnings concerning the validity of the result.", "type": "array", "items": { "$ref": "#/components/schemas/Warning" } } } }, "Suggestion": { "description": "A search text suggested for the input of the searchLocationsByText endpoint.", "type": "object", "required": [ "caption", "subCaption" ], "properties": { "caption": { "type": "string", "description": "A search address suggestion that can be displayed on a user interface as caption." }, "subCaption": { "type": "string", "description": "An additional address information for the suggestion that can be displayed on a user interface as sub caption." } } }, "LocationType": { "type": "string", "enum": [ "LOCALITY", "POSTAL_CODE", "STREET", "EXACT_ADDRESS", "INTERPOLATED_ADDRESS", "INTERSECTION", "POINT_OF_INTEREST" ], "x-enum-varnames": [ "LOCALITY", "POSTAL_CODE", "STREET", "EXACT_ADDRESS", "INTERPOLATED_ADDRESS", "INTERSECTION", "POINT_OF_INTEREST" ], "description": "Distinguishes different types of Locations: \n * `LOCALITY` - Represents a locality (town, city or place). \n * `POSTAL_CODE` - Represents a postal code area. \n * `STREET` - Represents a street, or a section of a street. \n * `EXACT_ADDRESS` - An address that is contained exactly in the geocoding data. \n * `INTERPOLATED_ADDRESS` - An address that was interpolated from an address range. \n * `INTERSECTION` - An at-grade junction where two streets meet. \n * `POINT_OF_INTEREST` - A point of interest, like e.g. a shop, a service, or a museum." }, "LocationProperties": { "required": [ "address", "referencePosition" ], "type": "object", "properties": { "referencePosition": { "$ref": "#/components/schemas/ReferencePosition" }, "roadAccessPosition": { "$ref": "#/components/schemas/RoadAccessPosition" }, "address": { "$ref": "#/components/schemas/Address" }, "formattedAddress": { "type": "string", "description": "A single string representing the address, typically consisting of the street, house number, postal code, city, and country. The precise format may differ based on what is appropriate for the address." }, "feedbackId": { "$ref": "#/components/schemas/FeedbackId" } } }, "Address": { "type": "object", "properties": { "countryName": { "type": "string", "description": "The country. In a response, it is represented by its full name (not abbreviated or encoded)." }, "state": { "type": "string", "description": "The name of the principal country subdivision which the address belongs to (for example, a state in the USA, or a canton in Switzerland)." }, "province": { "type": "string", "description": "The name of the second-level country subdivision which the address belongs to (for example, a county in the UK, or a province in Italy)." }, "postalCode": { "type": "string", "description": "The postal code of the address." }, "city": { "type": "string", "description": "The city of the address, i.e. the highest entity at the communal level which the address belongs to." }, "district": { "type": "string", "description": "The district of the address, i.e. the entity below city." }, "subdistrict": { "type": "string", "description": "The subdistrict of the address, i.e. the entity below district." }, "street": { "type": "string", "description": "The street of the address." }, "houseNumber": { "type": "string", "description": "The house number of the address." }, "countryCodeIsoAlpha2": { "type": "string", "description": "The country code according to [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)." }, "countryCodeIsoAlpha3": { "type": "string", "description": "The country code according to [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)." }, "countryCode": { "type": "string", "description": "The country or subdivision represented by its code according to [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) or [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) if referring to a subdivision." } }, "description": "Represents the address of a geographical object. Whenever a string, such as a city or street name, is available in multiple languages, it is returned in the default language specified by the country in which an object is located. Most of the fields are optional, because addressing schemes vary strongly between countries." }, "PlaceCategory": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "string", "description": "The identifier string of the place category." }, "name": { "type": "string", "description": "A human readable name for the place category." }, "description": { "type": "string", "description": "An explanation of what kind of places are part of this place category." } } }, "PlaceCategories": { "type": "object", "description": "Response type for place category requests.", "properties": { "placeCategories": { "type": "array", "description": "The individual place categories.", "items": { "$ref": "#/components/schemas/PlaceCategory" } } } }, "Quality": { "type": "object", "description": "Quality indicators that help deciding how well a result fits to the search input.", "properties": { "distance": { "type": "integer", "format": "int32", "description": "The spatial distance in \\[m\\] between the location or the place and the input of a position search. \n This is only available for **searchLocationsByPosition** and **searchPlacesByPosition**." }, "totalScore": { "type": "integer", "format": "int32", "description": "An overall score in \\[%\\] for address searches. 100 percent represents a perfect match between the input and the result. \n This is only available for **searchLocationsByText** and **searchLocationsByAddress** results." }, "addressScores": { "$ref": "#/components/schemas/AddressScores" } } }, "AddressScores": { "type": "object", "description": "Quality indicators that help deciding how well a result fits to the search input. \n This is only available for **searchLocationsByText** and **searchLocationsByAddress** results.", "properties": { "country": { "type": "integer", "format": "int32", "description": "The score for the returned country in \\[%\\]." }, "state": { "type": "integer", "format": "int32", "description": "The score for the returned state in \\[%\\]." }, "province": { "type": "integer", "format": "int32", "description": "The score for the returned province in \\[%\\]." }, "postalCode": { "type": "integer", "format": "int32", "description": "The score for the returned postalCode in \\[%\\]." }, "city": { "type": "integer", "format": "int32", "description": "The score for the returned city in \\[%\\]." }, "district": { "type": "integer", "format": "int32", "description": "The score for the returned district in \\[%\\]." }, "subDistrict": { "type": "integer", "format": "int32", "description": "The score for the returned subdistrict in \\[%\\]." }, "street": { "type": "integer", "format": "int32", "description": "The score for the returned street in \\[%\\]." }, "houseNumber": { "type": "integer", "format": "int32", "description": "The score for the returned house number in \\[%\\]." } } }, "FeedbackId": { "type": "string", "format": "uuid", "description": "A unique identifier for a location or a place in UUID format that can be used to provide feedback. It can also be used to provide feedback that none of the returned locations or places was a match. \n \n This is experimental and may change at any time in the future." }, "ErrorResponse": { "type": "object", "required": [ "description", "errorCode", "traceId" ], "example": { "traceId": "dc5b4c9a240458dd57128194dfbef0c8", "errorCode": "GENERAL_UNAUTHENTICATED", "description": "Invalid or missing authentication credentials.", "details": { "message": "Invalid API Key." } }, "properties": { "description": { "description": "A human readable message that describes the error.", "type": "string" }, "errorCode": { "description": "A constant string that can be used to identify this error class programmatically.\n\nIf additional information is available for an errorCode, it will be provided as key-value pairs with the parameter **details**. The keys available for a specific errorCode are documented directly with the errorCode. Unless stated otherwise, the values are of type string.\n\nAs an example, the following errorCode provides one key-value pair in the **details**. The key is called **message**.\n* `GENERAL_UNAUTHENTICATED` - Invalid or missing authentication credentials.\n * `message` - An additional error message.\n\nNote that additional errorCodes as well as the **details** of existing errorCodes may be added at any time. Furthermore, the **description** may change at any time. \n\n**HTTP status code: 400** \n* `GENERAL_VALIDATION_ERROR` - The validation of the request failed. Details can be found in **causes**. \n* `GENERAL_PARSING_ERROR` - The JSON syntax is invalid. \n\n**HTTP status code: 401** \n* `GENERAL_UNAUTHENTICATED` - Invalid or missing authentication credentials. \n * `message` - An additional error message. \n\n**HTTP status code: 403** \n* `GENERAL_FORBIDDEN` - Insufficient access rights. \n* `GENERAL_QUOTA_EXCEEDED` - The transaction limit is exceeded. \n * `message` - An additional error message. \n\n**HTTP status code: 404** \n* `GENERAL_RESOURCE_NOT_FOUND` - A requested resource does not exist. \n * `message` - An additional error message. \n\n**HTTP status code: 429** \n* `GENERAL_RATE_LIMIT_EXCEEDED` - The rate limit is exceeded. \n\n**HTTP status code: 500** \n* `GENERAL_INTERNAL_SERVER_ERROR` - The request could not be processed due to an internal error. \n * `message` - An additional error message. \n * `hint` - A hint how to solve the problem. \n\n**HTTP status code: 503** \n* `GENERAL_SERVICE_UNAVAILABLE` - The service is temporarily unavailable.", "type": "string" }, "traceId": { "description": "A unique identifier of the corresponding trace forest. It can be used to trace errors by the support.", "type": "string" }, "errorId": { "description": "A unique identifier specific to this error instance. It can be used to trace errors by the support.", "type": "string" }, "causes": { "description": "A list of affected parameters and/or properties that caused this error.", "type": "array", "items": { "$ref": "#/components/schemas/CausingError" } }, "details": { "description": "Additional properties specific to this error class.", "type": "object", "additionalProperties": true } } }, "CausingError": { "type": "object", "required": [ "description", "errorCode" ], "properties": { "description": { "description": "A human readable message that describes the error.", "type": "string" }, "errorCode": { "description": "A constant string that can be used to identify this error class programmatically.\n\nIf additional information is available for an errorCode, it will be provided as key-value pairs with the parameter **details**. The keys available for a specific errorCode are documented directly with the errorCode. Unless stated otherwise, the values are of type string.\n\nAs an example, the following errorCode provides one key-value pair in the **details**. The key is called **value**.\n* `GENERAL_INVALID_VALUE` - A parameter is set to an invalid value.\n * `value` - The invalid value.\n\nNote that additional errorCodes as well as the **details** of existing errorCodes may be added at any time. Furthermore, the **description** may change at any time. \n\n**Error codes for** `GENERAL_VALIDATION_ERROR`\n* `GENERAL_INVALID_VALUE` - A parameter is set to an invalid value. \n * `value` - The invalid value. \n* `GENERAL_UNRECOGNIZED_PARAMETER` - A parameter is unknown. \n* `GENERAL_MISSING_PARAMETER` - A required parameter is missing. \n* `GENERAL_DUPLICATE_PARAMETER` - A parameter is duplicated. \n* `GENERAL_MINIMUM_VALUE_VIOLATED` - The minimum value of a parameter is violated. \n * `minimumValue` - The minimum value (integer or double). \n* `GENERAL_MAXIMUM_VALUE_VIOLATED` - The maximum value of a parameter is violated. \n * `maximumValue` - The maximum value (integer or double). \n* `GENERAL_MINIMUM_ITEMS_VIOLATED` - The minimum number of items of an array is violated. \n * `minimumItems` - The minimum number of items (integer). \n* `GENERAL_MAXIMUM_ITEMS_VIOLATED` - The maximum number of items of an array is violated. \n * `maximumItems` - The maximum number of items (integer). \n* `GEOCODING_PARAMETER_CONFLICT` - Conflicting parameters found. Only one of them is allowed. \n * `conflictingParameter` - The name of the conflicting parameter.\n* `GEOCODING_PARAMETER_DEPENDENCY_VIOLATED` - A parameter depends on another parameter which is missing. \n * `missingParameter` - The name of the missing parameter. \n* `GENERAL_TYPE_VIOLATED` - The value of a parameter has an invalid type. \n * `type` - The type. \n* `GENERAL_FORMAT_VIOLATED` - The value of a parameter has an invalid format.\n * `format` - The format.\n* `GENERAL_PATTERN_VIOLATED` - The value of a string parameter does not satisfy the required pattern. \n * `pattern` - The pattern. \n* `GENERAL_ENUM_VIOLATED` - The value of a parameter is not one of the specified enum values. \n * `enum` - The allowed enum values.", "type": "string" }, "parameter": { "description": "The name of the affected query or path parameter or a JSONPath to the affected property of the request.", "type": "string" }, "details": { "description": "Additional properties specific to this error class.", "type": "object", "additionalProperties": true } } }, "Warning": { "type": "object", "required": [ "description", "warningCode" ], "properties": { "description": { "description": "A human readable message that describes the warning.", "type": "string" }, "warningCode": { "description": "A constant string that can be used to identify this warning class programmatically.\n\nIf additional information is available for a warningCode, it will be provided as key-value pairs with the parameter **details**. The keys available for a specific warningCode are documented directly with the warningCode. Unless stated otherwise, the values are of type string.\n\nAs an example, the following warningCode provides four key-value pairs in the **details**. \nThe keys are called **parameter**, **value**, **relatedParameter** and **relatedValue**.\n* `GENERAL_PARAMETER_IGNORED` - A parameter was ignored.\n * `parameter` - The ignored parameter.\n * `value` - The value of the ignored parameter.\n * `relatedParameter` - The parameter which caused the parameter in question to be ignored.\n * `relatedValue` - The value which caused the parameter in question to be ignored. Not present if the conflict is independent of the value.\n\nNote that additional warningCode as well as the **details** of existing warningCode may be added at any time. Furthermore, the **description** may change at any time. \n\n* `GEOCODING_COUNTRY_FILTER_MODIFIED` - A given code in **countryFilter** referring to a subdivision of a country was modified to its corresponding country code. \n * `requestedSubdivisionCode` - The subdivision code that was originally requested. \n * `fallbackCountryCode` - The country code that was used as a fallback in the search. \n* `GEOCODING_TIMEOUT` - The search ran into a timeout while trying to find results. \n* `GEOCODING_INPUT_TOO_LONG` - The input was rejected because it is too long. \n * `maximumSize` - The maximum allowed size of the single input field. \n* `TOO_MANY_INPUT_WORDS` - At least one of the input fields exceeded the maximum number of input words. \n * `inputField` - The input field that had too many input words.\n * `actualNumberOfWords` - The number of words found in `inputField`.\n * `maximumAllowedNumberOfWords` - The maximum number of words allowed in `inputField`.\n* `GEOCODING_TOO_MANY_RESULTS` - Too many results found. Not all of them are provided in the response. ", "type": "string" }, "details": { "description": "Additional properties specific to this class of warnings.", "type": "object", "additionalProperties": true } } }, "InputField": { "type": "string", "description": "Enumeration to specify a parameter of a suggestions/by-address request. \n * `COUNTRY` - Specifies the country parameter. \n * `STATE` - Specifies the state parameter. \n * `POSTAL_CODE` - Specifies the postalCode parameter. \n * `LOCALITY` - Specifies the locality parameter. \n * `STREET` - Specifies the street parameter. \n * `HOUSE_NUMBER` - Specifies the houseNumber parameter.", "enum": [ "COUNTRY", "STATE", "POSTAL_CODE", "LOCALITY", "STREET", "HOUSE_NUMBER" ], "x-enum-varnames": [ "COUNTRY", "STATE", "POSTAL_CODE", "LOCALITY", "STREET", "HOUSE_NUMBER" ] }, "Results": { "type": "string", "enum": [ "ADDRESS_SCORES" ], "x-enum-varnames": [ "ADDRESS_SCORES" ] }, "TotalScoreType": { "type": "string", "description": "Enumeration to specify the type of total score calculation. \n * `INPUT_AND_RESULT_BASED` - The total score is calculated by comparing the result against the input. \n * `RESULT_BASED` - The total score is calculated by classifying result attributes. \n \n This parameter is experimental and may change at any time in the future.", "enum": [ "INPUT_AND_RESULT_BASED", "RESULT_BASED" ], "x-enum-varnames": [ "INPUT_AND_RESULT_BASED", "RESULT_BASED" ], "default": "INPUT_AND_RESULT_BASED" } }, "parameters": { "LatitudeParameter": { "name": "latitude", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Latitude" } }, "LongitudeParameter": { "name": "longitude", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Longitude" } }, "RadiusParameter": { "name": "radius", "in": "query", "description": "The search radius [m] around the given position.", "schema": { "type": "integer", "format": "int32", "default": 1000, "minimum": 0, "maximum": 10000 } }, "CountryFilterParameter": { "name": "countryFilter", "in": "query", "explode": false, "description": "A comma-separated list of country codes according to [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) or [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) if referring to a subdivision. The search will only consider data from countries with these codes. If no filter is specified, all countries are taken into account. However, empty values are not allowed. \n If a given subdivision code is not supported, only the first two digits referring to the country are considered in the search and a **warningCode** `GEOCODING_COUNTRY_FILTER_MODIFIED` is returned with the response.", "schema": { "type": "array", "items": { "type": "string", "pattern": "[A-Z]{2}|[A-Z]{2}-[A-Z0-9]{1,3}" } }, "example": [ "DE", "FR" ] }, "CategoryFilterParameter": { "name": "categoryFilter", "in": "query", "explode": false, "description": "A comma-separated list of place category IDs. Only results having one of these categories will be returned. If no filter is specified, all categories will be returned. However, empty values are not allowed.", "schema": { "type": "array", "items": { "type": "string", "pattern": "[^\\\\\\\"\\'\\r\\t\\f\\v]+" } }, "example": [ "navteq-lcms:700-7200-0328", "navteq-lcms:700-7400-0292" ] }, "CleanInputParameter": { "name": "cleanInput", "in": "query", "description": "If set to `true`, the service will try (for certain countries) to clean the input in a pre-processing step. This helps to expedite processing if the input is a free-form text that may contain garbage. This flag may influence the scores in the response. For more details see the corresponding [concept](./concepts/clean-input). \n \n This parameter is experimental and may change at any time in the future.", "schema": { "type": "boolean", "default": false } }, "TotalScoreTypeParameter": { "name": "totalScoreType", "in": "query", "description": "Defines how Location.quality.totalScore is calculated. \n * `INPUT_AND_RESULT_BASED` - The total score is calculated by comparing the result against the input. \n * `RESULT_BASED` - The total score is calculated by classifying result attributes. \n \n This parameter is experimental and may change at any time in the future.", "schema": { "$ref": "#/components/schemas/TotalScoreType" } }, "LimitParameter": { "name": "limit", "in": "query", "description": "Limits the number of results that are returned.", "schema": { "type": "integer", "format": "int32", "default": 5, "minimum": 0 } }, "LanguageParameter": { "name": "language", "in": "query", "description": "The preferred language for the response formatted according to [ISO-639-1](https://www.loc.gov/standards/iso639-2/php/code_list.php) for languages or [BCP47](https://tools.ietf.org/html/bcp47) for language variants. By default the service uses the language spoken in the country or region of the result. In case the given preferred language is not available in the data, the default language is used.", "schema": { "type": "string", "pattern": "[a-zA-Z]{1,8}(-[a-zA-Z0-9]{1,8})*" }, "example": "en" }, "CenterParameter": { "name": "center", "in": "query", "explode": false, "description": "Defines a search center. The format of the `center` parameter is a comma-separated pair of double values setting the latitude and longitude, i. e. `,`. The values for the latitude from south to north between -90 and 90 and for the longitude between -180 and 180 from west to east are in degrees (WGS84/EPSG:4326).", "schema": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number", "format": "double" } }, "example": [ 49.0131, 8.4279 ] }, "CenterFilterParameter": { "name": "center", "in": "query", "explode": false, "description": "Defines a circular search context. The format of the `center` parameter is a comma-separated pair of double values setting the latitude and longitude, i. e. `,`. The values for the latitude from south to north between -90 and 90 and for the longitude between -180 and 180 from west to east are in degrees (WGS84/EPSG:4326). A certain radius around the center is considered and this can be adapted by setting the parameter `radius` in addition. Note: The parameters `center` respectively `radius` and `boundingBox` (if available) are mutually exclusive.", "schema": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number", "format": "double" } }, "example": [ 49.0131, 8.4279 ] }, "BoundingBoxParameter": { "name": "boundingBox", "in": "query", "explode": false, "description": "Defines a rectangular search context. The format of the `boundingBox` parameter is a comma-separated list of double values setting the maximum latitude _top_, the minimum longitude _left_, the minimum latitude _bottom_ and the maximum longitude _right_, i. e. `,,,`. The values for _top_ and _bottom_ from south to north between -90 and 90 as well as for _left_ and _right_ between -180 and 180 from west to east are in degrees (WGS84/EPSG:4326). Note: The parameters `boundingBox` and `center` respectively `radius` are mutually exclusive.", "schema": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "number", "format": "double" } }, "example": [ 49.0135, 8.4279, 49.0124, 8.4308 ] }, "InputFieldParameter": { "name": "inputField", "in": "query", "required": true, "description": "Used to specify for which parameter of the suggestions/by-address request a suggestion is desired.", "schema": { "$ref": "#/components/schemas/InputField" } }, "FeedbackIdParameter": { "name": "feedbackId", "in": "query", "description": "A unique identifier for a location or a place in UUID format that can be used to provide feedback.", "required": true, "schema": { "$ref": "#/components/schemas/FeedbackId" } }, "ResultsParameter": { "name": "results", "in": "query", "description": "Comma-separated list that defines which results will be returned.\n * `ADDRESS_SCORES` - Populate **location.quality.addressScores**.", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Results" } }, "example": [ "ADDRESS_SCORES" ] }, "MinimumPopulationParameter": { "name": "minimumPopulation", "in": "query", "description": "If specified, the response contains only the nearest city or town with at least the given population. The **locationType** of this result will be _LOCALITY_, street information will not be returned.\n\nThis parameter is in an experimental state and may change at any time.", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "example": 50000 } }, "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "apiKey" } } }, "security": [ { "apiKeyAuth": [] } ], "servers": [ { "url": "https://api.myptv.com/geocoding/v1" } ] }