{"openapi":"3.1.0","info":{"title":"HERE Batch API v7","description":"API for processing large numbers of Geocode, Reverse Geocoding, and Lookup by ID requests.\n## \"ALPHA\" & \"BETA\" tags\n\nAPI requests parameters and response fields can be tagged with one of the following maturity qualifiers: alpha, beta\n- \"ALPHA\" tagged features are in mid-stage development. They can change or in rare cases be removed. No backward compatibility is guaranteed nor bug service level agreement (SLA) do apply. Customers using ALPHA features are advised not use them in production.\n- \"BETA\" tagged features are in end-stage development. They are backward compatible and can not be removed. They have no major bug, but coverage, quality, performance, or test coverage is not considered final. Customers can safely use BETA features in their applications if they accept those limitations and potential behavior refinements.\n\n## \"RESTRICTED\" tag\n\nAPI requests parameters and response fields can be tagged with the privilege qualifier \"RESTRICTED\". Such features are only available to customers having a specific contract with HERE. Unauthorized usages are typically leading to a http status code 403.","license":{"name":"HERE Documentation License","url":"https://legal.here.com/en-gb/terms/documentation-license"},"version":"7.40.0"},"externalDocs":{"description":"The developer guide and changelog are available here.","url":"https://www.here.com/docs/bundle/batch-api-developer-guide/page/README.html"},"servers":[{"url":"https://batch.search.hereapi.com/v7","description":"Production environment URL"}],"security":[{"ApiKey":[]},{"Bearer":[]}],"tags":[{"name":"Batch jobs","description":"API for creating and managing Batch jobs on Location Services"},{"name":"Batch notifications (BETA)","description":"API for creating and managing notifications. E.g. webhooks."},{"name":"API Information","description":"Additional API Information"}],"paths":{"/batch/jobs":{"get":{"tags":["Batch jobs"],"summary":"Returns the details of multiple jobs","description":"Fetches the details of all jobs the user is authorized to access - filtered on criteria provided in the query.\n\nIf **none** of the jobs matches criteria, an empty array is returned in the `200 - OK` response.","operationId":"getJobs","parameters":[{"name":"limit","in":"query","description":"Limits the number of results returned in the response. Default value is 100.","required":false,"schema":{"type":"integer","format":"int32","default":100,"maximum":100,"minimum":1},"example":100},{"name":"offset","in":"query","description":"For supporting paging by offset - the result list will start at the given offset. Default is 0.","required":false,"schema":{"type":"integer","format":"int32","default":0,"minimum":0},"example":0},{"name":"status","in":"query","description":"Filter on jobs with this status.","required":false,"schema":{"type":"string","default":"any","enum":["any","submitted","queued","pending","inProgress","completed","stopped","failure"]}},{"name":"tag","in":"query","description":"A user supplied string that denotes one or more jobs.\n\nCan be used to filter job responses on delete and get operations.","required":false,"schema":{"type":"string"}},{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"responses":{"200":{"description":"Page with an array of the details of all jobs matching the supplied criteria.\n\nEmpty if none matched the criteria.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedJobDetailResponse"}}}},"401":{"description":"API response in case of unauthorized access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Unauthorized":{"$ref":"#/components/examples/UnauthorizedErrorExample"}}}}},"403":{"description":"API response in case of forbidden access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Forbidden":{"$ref":"#/components/examples/ForbiddenErrorExample"}}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKey":[]},{"Bearer":[]}]},"post":{"tags":["Batch jobs"],"summary":"Creates a new job","description":"Creates a new job from the supplied input and query parameters.\n\nA `201 - CREATED` response returns the job's unique ID, which should be used in future operations on the job.","operationId":"postJob","parameters":[{"name":"serviceHrn","in":"query","description":"The HERE Resource Name identifier of the Service targeted by the job.","required":true,"schema":{"type":"string","default":"hrn:here:service::olp-here:search-geocode-7","enum":["hrn:here:service::olp-here:search-geocode-7","hrn:here:service::olp-here:search-revgeocode-7","hrn:here:service::olp-here:search-lookup-7"]}},{"name":"tag","in":"query","description":"A user supplied string that denotes one or more jobs.\n\nCan be used to filter job responses on delete and get operations.","required":false,"schema":{"type":"string"}},{"name":"billingTags","in":"query","description":"A user supplied string that specifies the billing tags of the job.\n\nUp to six billing tags can be concatenated either with plus (+) or comma (,) sign to a long string (do not mix). Duplicates will be ignored (taken as single).\n\nMust be between 4-16 characters, case sensitive.\n\nAllowed characters are alpha/numeric ASCII characters  [A-Za-z0-9] and the following special characters (not begin or end with): - _.","required":false,"schema":{"type":"string"}},{"name":"inputDelimiter","in":"query","description":"Character used to delimit fields in the job input.\n\nWill be ignored if the input is supplied as URL query strings. Max length 2 is reserved for \\t as delimiter","required":false,"schema":{"type":"string","default":"|","maxLength":2,"minLength":1}},{"name":"outputDelimiter","in":"query","description":"Character used to delimit fields in the job results.\n\nCertain characters, specifically: ` .\"()` (spaces, the period, quotes and parentheses) are not supported as delimiters for output.","required":false,"schema":{"type":"string","default":"|","maxLength":2,"minLength":1}},{"name":"inputColumns","in":"query","description":"A format descriptor used to interpret fields in the job input.\n\nEvery record in the input will be split by the input delimiter and compared to the  supplied format descriptor during processing, if the record does not conform to the format description the record will be marked as invalid.\n\nEvery record will be identified by a record identifier (called `recId` in the format descriptor). You can choose to have the record identifiers be **auto-generated** for you by **leaving out** `recId` in the header or input format descriptor.\n\nThe format descriptor can be left **empty** if the  input has a header describing the format, or is formatted as requests in the URL query format.","required":false,"schema":{"type":"string","maxLength":1024,"minLength":1},"examples":{"Geocoding":{"description":"Example Header for the Geocoding Service","value":"recId|q|in|lang|limit"},"Reverse Geocoding":{"description":"Example Header for the Reverse Geocoding Service","value":"recId|at|lang|limit"},"Lookup-by-ID":{"description":"Example Header for the Lookup-by-ID Service","value":"recId|id"}}},{"name":"outputColumns","in":"query","description":"A descriptor used to format fields in the job results.\n\nEvery result in the output will be split by the output delimiter and formatted according to the supplied descriptor during processing.\n\nFields supported by the API will be interpreted, those that are not will be ignored. A field is recognized by matching it to an expected name or variants of that name. Character casing (i.e. lowercase or UPPERCASE) is ignored.\n\nGeneral response parameters (such as `recId`) always precede the service specific parameters in the Job's output format and need not be specified in the format descriptor.\n\nIf the format descriptor is absent a default output format is used.","required":false,"schema":{"type":"string","maxLength":1024,"minLength":1},"example":"position|title|id"},{"name":"outputFilter","in":"query","description":"In case the 'outputType=jsonl' the formater supports json filtering in a basic json path format like 'title,id,address.label,address.streets,access.lat,position', where each path segment can either be an object or array property name (e.g. 'access' is an array with sub objects).\n - The single segments are always seperated by a comma ','. The outputDelimiter is ignored in this case.\n - The filtering is **case sensitive**.\n - If a property is not found it is ignored.\n - Individually selecting objects within an array is not possible, the next path segment to filter will always be applied to all features within an array.\n","required":false,"schema":{"type":"string","maxLength":1024,"minLength":1}},{"name":"startJob","in":"query","description":"A boolean value (true/false) indicating if a job should be started immediately\nafter creation. Default value is true.","required":false,"schema":{"type":"boolean","default":true}},{"name":"outputType","in":"query","description":"**ALPHA** The output type for the result file of the submitted batch job. For now csv (default) and jsonl are supported.","required":false,"schema":{"type":"string","default":"csv","enum":["csv","jsonl"]}},{"name":"notificationIds","in":"query","description":"(BETA) The UUIDs of the notification hooks that are called at the end of a job.\n\nThe notifications need to exist up front and be owned by the calling principle. Multiple notifications can be seperated by ','. (Max. 5 per job)","required":false,"schema":{"type":"string"}},{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"requestBody":{"description":"The job's input as text, structured and delimited, with an optional header describing the format.\n\nEach line of text is interpreted as a request to the targeted Service.\n\nEvery request will be identified by a record identifier (called `recId` in the input header). You can choose to have the record identifiers be **auto-generated** for you by **leaving out** `recId` in the header or input format descriptor.","content":{"text/plain":{"schema":{"type":"string"},"examples":{"Geocoder job input (with header)":{"$ref":"#/components/examples/GeocoderJobInputWithHeader"},"Geocoder job input (as URL queries)":{"$ref":"#/components/examples/GeocoderJobInputAsURLQuery"},"Reverse Geocoder job input (with header)":{"$ref":"#/components/examples/ReverseGeocoderJobInputWithHeader"},"Reverse Geocoder job input (as URL queries)":{"$ref":"#/components/examples/ReverseGeocoderJobInputAsURLQuery"},"Lookup job input (with header)":{"$ref":"#/components/examples/LookupJobInputWithHeader"},"Lookup job input (as URL queries)":{"$ref":"#/components/examples/LookupJobInputAsURLQuery"}}},"text/csv":{"schema":{"type":"string"}}}},"responses":{"201":{"description":"Response on successful creation of the job.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"},"examples":{"Geocoder job":{"$ref":"#/components/examples/GeocoderJobSubmittedExample"},"Reverse Geocoder job":{"$ref":"#/components/examples/ReverseGeocoderJobSubmittedExample"}}}}},"400":{"description":"Response when a particular request parameter is considered invalid or could not be parsed correctly.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"Argument Exceeds Length Limit":{"$ref":"#/components/examples/ArgumentExceedsMaxLengthErrorExample"},"Input Exceeds Size Limit":{"$ref":"#/components/examples/InputExceedsMaxSizeErrorExample"},"Unsupported Delimiter Character":{"$ref":"#/components/examples/CharacterDelimiterUnsupportedErrorExample"}}}}},"401":{"description":"API response in case of unauthorized access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Unauthorized":{"$ref":"#/components/examples/UnauthorizedErrorExample"}}}}},"403":{"description":"API response in case of forbidden access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Forbidden":{"$ref":"#/components/examples/ForbiddenErrorExample"}}}}},"404":{"description":"API response when the Service with the specified HRN could not be found or is unsupported.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"Service Unsupported":{"$ref":"#/components/examples/ServiceUnsupportedErrorExample"}}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKey":[]},{"Bearer":[]}]},"delete":{"tags":["Batch jobs"],"summary":"Deletes multiple jobs","description":"Deletes all jobs the user is authorized to access, filtered on criteria provided in the query.\n\nIf **none** of the jobs matches the criteria, a `200 - OK` response is returned with an empty list of job IDs.\n\n","operationId":"deleteJobs","parameters":[{"name":"status","in":"query","description":"Filter on jobs with this status.","required":true,"schema":{"type":"string","enum":["any","submitted","queued","pending","inProgress","completed","stopped","failure"]}},{"name":"tag","in":"query","description":"A user supplied string that denotes one or more jobs.\n\nCan be used to filter job responses on delete and get operations.","required":false,"schema":{"type":"string"}},{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"responses":{"200":{"description":"Listing of all the jobs that were deleted.\n\nIf *none* were deleted, the `total` will be `0`.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobsDeletedResponse"}}}},"401":{"description":"API response in case of unauthorized access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Unauthorized":{"$ref":"#/components/examples/UnauthorizedErrorExample"}}}}},"403":{"description":"API response in case of forbidden access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Forbidden":{"$ref":"#/components/examples/ForbiddenErrorExample"}}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKey":[]},{"Bearer":[]}]}},"/batch/jobs/{jobId}":{"get":{"tags":["Batch jobs"],"summary":"Returns the details of a job","description":"Fetches the details of the job with the specified ID.","operationId":"getJob","parameters":[{"name":"jobId","in":"path","description":"Identifier that was auto-generated on job creation and uniquely identifies the job.","required":true,"schema":{"type":"string","minLength":1},"example":"JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6"},{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"responses":{"200":{"description":"The details of the job found.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobDetailResponse"}}}},"401":{"description":"API response in case of unauthorized access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Unauthorized":{"$ref":"#/components/examples/UnauthorizedErrorExample"}}}}},"403":{"description":"API response in case of forbidden access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Forbidden":{"$ref":"#/components/examples/ForbiddenErrorExample"}}}}},"404":{"description":"API response when the job with the specified ID could not be located.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"Job not found":{"$ref":"#/components/examples/JobNotFoundErrorExample"}}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKey":[]},{"Bearer":[]}]},"delete":{"tags":["Batch jobs"],"summary":"Deletes a job","description":"Deletes a job.","operationId":"deleteJob","parameters":[{"name":"jobId","in":"path","description":"Identifier that was auto-generated on job creation and uniquely identifies the job.","required":true,"schema":{"type":"string","minLength":1},"example":"JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6"},{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"responses":{"200":{"description":"Listing of the job that was deleted.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"},"examples":{"Job deleted":{"$ref":"#/components/examples/GeocoderJobDeletedExample"}}}}},"401":{"description":"API response in case of unauthorized access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Unauthorized":{"$ref":"#/components/examples/UnauthorizedErrorExample"}}}}},"403":{"description":"API response in case of forbidden access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Forbidden":{"$ref":"#/components/examples/ForbiddenErrorExample"}}}}},"404":{"description":"API response when the job with the specified ID could not be located.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"Job not found":{"$ref":"#/components/examples/JobNotFoundErrorExample"}}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKey":[]},{"Bearer":[]}]}},"/batch/jobs/{jobId}/errors":{"get":{"tags":["Batch jobs"],"summary":"Returns the errors of a job","description":"Fetches the errors of the job with the specified ID, given that it has completed with errors, as a downloadable stream of data.\n\nIf the job does not yet have any errors available, this operation responds with a `404 - NOT FOUND` response.\nIf the job did not produce any errors, the operation responds with a `204 - NO CONTENT` response","operationId":"getJobErrors","parameters":[{"name":"jobId","in":"path","description":"Identifier that was auto-generated on job creation and uniquely identifies the job.","required":true,"schema":{"type":"string","minLength":1},"example":"JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6"},{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"responses":{"200":{"description":"The errors of the job as a downloadable stream. Each line is a reference to the input line and error details from backend service. ","headers":{"Transfer-Encoding":{"description":"Encoding is expected to be `chunked` for streaming downloads of unknown size","style":"simple","schema":{"type":"string","example":"chunked"}},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"},"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"Content-Disposition":{"description":"The format is expected to be `attachment` or `attachment; filename=\"JOB-<id>-results.txt\"`","style":"simple","schema":{"type":"string","example":"attachment; filename=\"JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6-results.csv\""}},"Content-Encoding":{"description":"Content may be compressed to reduce bandwidth requirements","style":"simple","schema":{"type":"string","example":"gzip"}}},"content":{"text/plain":{"schema":{"type":"string","format":"binary"}}}},"204":{"description":"API response when the job has completed without generating any errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"text/plain":{"schema":{"type":"null"}}}},"401":{"description":"API response in case of unauthorized access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Unauthorized":{"$ref":"#/components/examples/UnauthorizedErrorExample"}}}}},"403":{"description":"API response in case of forbidden access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Forbidden":{"$ref":"#/components/examples/ForbiddenErrorExample"}}}}},"404":{"description":"API response when either:\n - a job with the specified ID could not be located, or\n - the errors of the job are not available, yet.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKey":[]},{"Bearer":[]}]}},"/batch/jobs/{jobId}/results":{"get":{"tags":["Batch jobs"],"summary":"Returns the results of a job","description":"Fetches the results of the job with the specified ID, given that it has completed successfully, as a downloadable stream of data.\n\nIf the job does not (yet) have  any results available, this operation responds with a `404 - NOT FOUND` response.","operationId":"getJobResults","parameters":[{"name":"jobId","in":"path","description":"Identifier that was auto-generated on job creation and uniquely identifies the job.","required":true,"schema":{"type":"string","minLength":1},"example":"JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6"},{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"responses":{"200":{"description":"The results of the job as a downloadable stream. Formatted according to the output format descriptor provided during creation/modification of the job. ","headers":{"Transfer-Encoding":{"description":"Encoding is expected to be `chunked` for streaming downloads of unknown size","style":"simple","schema":{"type":"string","example":"chunked"}},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"},"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"Content-Disposition":{"description":"The format is expected to be `attachment` or `attachment; filename=\"JOB-<id>-results.txt\"`","style":"simple","schema":{"type":"string","example":"attachment; filename=\"JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6-results.txt\""}},"Content-Encoding":{"description":"Content may be compressed to reduce bandwidth requirements","style":"simple","schema":{"type":"string","example":"gzip"}}},"content":{"text/plain":{"schema":{"type":"string","format":"binary"},"examples":{"Geocoder job results":{"$ref":"#/components/examples/GeocoderJobOutput"}}}}},"204":{"description":"API response when the job has no results.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"text/plain":{"schema":{"type":"null"}}}},"401":{"description":"API response in case of unauthorized access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Unauthorized":{"$ref":"#/components/examples/UnauthorizedErrorExample"}}}}},"403":{"description":"API response in case of forbidden access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Forbidden":{"$ref":"#/components/examples/ForbiddenErrorExample"}}}}},"404":{"description":"API response when either:\n - a job with the specified ID could not be located, or\n - the results of the job is unavailable.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"Job Not Found":{"$ref":"#/components/examples/JobNotFoundErrorExample"},"Job Results Not Found":{"$ref":"#/components/examples/JobResultsUnavailableErrorExample"}}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKey":[]},{"Bearer":[]}]}},"/batch/jobs/{jobId}/start":{"put":{"tags":["Batch jobs"],"summary":"Starts a job","description":"Schedules a job for immediate execution and responds with a `200 - OK` if successful.\nIf the job is already running this operation does nothing and will respond with the same `200 - OK` response.\n\nIf the job was previously halted, this operation will continue execution from the point where it was stopped.\nIf you wish to restart a job from its beginning, you should create a new job and delete the existing one.\n\nTake note, this operation will return a `429 - TOO MANY REQUESTS` if the allowed number of concurrently running jobs is exceeded.","operationId":"startJob","parameters":[{"name":"jobId","in":"path","description":"Identifier that was auto-generated on job creation and uniquely identifies the job.","required":true,"schema":{"type":"string","minLength":1},"example":"JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6"},{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"responses":{"200":{"description":"Response if the job was successfully scheduled for execution.\n\nThe job's status will change to `queued` if the job was successfully validated and scheduled for execution.\n\nWhen the job starts execution the status will change to `inProgress`.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"},"examples":{"Geocoder job":{"$ref":"#/components/examples/GeocoderJobPendingExample"},"Reverse Geocoder job":{"$ref":"#/components/examples/ReverseGeocoderJobPendingExample"}}}}},"400":{"description":"Response if the job could not be executed due to incomplete request information.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"API response in case of unauthorized access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Unauthorized":{"$ref":"#/components/examples/UnauthorizedErrorExample"}}}}},"403":{"description":"API response in case of forbidden access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Forbidden":{"$ref":"#/components/examples/ForbiddenErrorExample"}}}}},"404":{"description":"API response when the job with the specified ID could not be located.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"Job not found":{"$ref":"#/components/examples/JobNotFoundErrorExample"}}}}},"429":{"description":"Response if the allowed number of concurrently running jobs is exceeded.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"Too many concurrent jobs":{"$ref":"#/components/examples/MaxConcurrentJobsErrorExample"}}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKey":[]},{"Bearer":[]}]}},"/batch/jobs/{jobId}/stop":{"put":{"tags":["Batch jobs"],"summary":"Stops a job","description":"This operation will schedule a job to be halted and responds with a `200 - OK` if successful. If the job is **not** currently running, then this operation does  nothing but will still return a `200 - OK` response.\n\nOnce the job has been stopped, you can continue from where the job halted by starting it again.","operationId":"stopJob","parameters":[{"name":"jobId","in":"path","description":"Identifier that was auto-generated on job creation and uniquely identifies the job.","required":true,"schema":{"type":"string","minLength":1},"example":"JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6"},{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"responses":{"200":{"description":"Response if the job was successfully scheduled to be halted. The job's status will change to `stopped` once the job is successfully halted.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"},"examples":{"Geocoder job":{"$ref":"#/components/examples/GeocoderJobStoppedExample"},"Reverse Geocoder job":{"$ref":"#/components/examples/ReverseGeocoderJobStoppedExample"}}}}},"401":{"description":"API response in case of unauthorized access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Unauthorized":{"$ref":"#/components/examples/UnauthorizedErrorExample"}}}}},"403":{"description":"API response in case of forbidden access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Forbidden":{"$ref":"#/components/examples/ForbiddenErrorExample"}}}}},"404":{"description":"API response when the job with the specified ID could not be located.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"Job not found":{"$ref":"#/components/examples/JobNotFoundErrorExample"}}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKey":[]},{"Bearer":[]}]}},"/batch/notifications":{"get":{"tags":["Batch notifications (BETA)"],"summary":"(BETA) Get all notifications","description":"(BETA) Get all notifications that the current client has access to.","operationId":"getNotifications","parameters":[{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Notification"}}}},"401":{"description":"API response in case of unauthorized access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Unauthorized":{"$ref":"#/components/examples/UnauthorizedErrorExample"}}}}},"403":{"description":"API response in case of forbidden access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Forbidden":{"$ref":"#/components/examples/ForbiddenErrorExample"}}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKey":[]},{"Bearer":[]}]},"post":{"tags":["Batch notifications (BETA)"],"summary":"(BETA) Create a new notification","description":"(BETA) Create a new notification.\n\nTo configure a notification, the **type** as well as the the **config** property needs to be defined. Each type requires individual properties as listed below.\n\n### `webHook`\nFor the notification of the type `webHook` only a **url** parameter is required. This URL is called via a GET request, after the job is completed.\nTo individualize the request, property placeholders in the URL are substituted if surrounded by '${' and '}' These placeholders can be in the path or a query parameter.\n\nAvailable properties are:\n - JOB_ID\n - JOB_NAME\n - JOB_STATUS\n - JOB_OUTPUT_TYPE\n - JOB_RECORDS_SUCCEEDED\n - JOB_RECORDS_FAILED\n - JOB_RECORDS_TOTAL\n - JOB_RECORDS_VALID\n - JOB_RECORDS_INVALID\n\nAn example for the url property would be: 'https://myPublicDomain.de?jobId=${JOB_ID}&status=${JOB_STATUS}'","operationId":"postNotification","parameters":[{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"requestBody":{"description":"The notification to create.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Notification"}}},"required":true},"responses":{"201":{"description":"Created","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Notification"}}}},"401":{"description":"API response in case of unauthorized access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Unauthorized":{"$ref":"#/components/examples/UnauthorizedErrorExample"}}}}},"403":{"description":"API response in case of forbidden access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Forbidden":{"$ref":"#/components/examples/ForbiddenErrorExample"}}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKey":[]},{"Bearer":[]}]}},"/batch/notifications/{notificationId}":{"get":{"tags":["Batch notifications (BETA)"],"summary":"(BETA) Get a notification","description":"(BETA) Get a notification by id.","operationId":"getNotification","parameters":[{"name":"notificationId","in":"path","description":"Identifier that was auto-generated on notification creation and uniquely identifies the notification.","required":true,"schema":{"type":"string","minLength":1},"example":"NOTIFICATION-3fa85f64-5717-4562-b3fc-2c963f66afa6"},{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Notification"}}}},"401":{"description":"API response in case of unauthorized access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Unauthorized":{"$ref":"#/components/examples/UnauthorizedErrorExample"}}}}},"403":{"description":"API response in case of forbidden access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Forbidden":{"$ref":"#/components/examples/ForbiddenErrorExample"}}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKey":[]},{"Bearer":[]}]},"put":{"tags":["Batch notifications (BETA)"],"summary":"(BETA) Replace a notification","description":"(BETA) Replace a notification.\n\nTo configure a notification, the **type** as well as the the **config** property needs to be defined. Each type requires individual properties as listed below.\n\n### `webHook`\nFor the notification of the type `webHook` only a **url** parameter is required. This URL is called via a GET request, after the job is completed.\nTo individualize the request, property placeholders in the URL are substituted if surrounded by '${' and '}' These placeholders can be in the path or a query parameter.\n\nAvailable properties are:\n - JOB_ID\n - JOB_NAME\n - JOB_STATUS\n - JOB_OUTPUT_TYPE\n - JOB_RECORDS_SUCCEEDED\n - JOB_RECORDS_FAILED\n - JOB_RECORDS_TOTAL\n - JOB_RECORDS_VALID\n - JOB_RECORDS_INVALID\n\nAn example for the url property would be: 'https://myPublicDomain.de?jobId=${JOB_ID}&status=${JOB_STATUS}'","operationId":"putNotification","parameters":[{"name":"notificationId","in":"path","description":"Identifier that was auto-generated on notification creation and uniquely identifies the notification.","required":true,"schema":{"type":"string","minLength":1},"example":"NOTIFICATION-3fa85f64-5717-4562-b3fc-2c963f66afa6"},{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Notification"}}},"required":true},"responses":{"200":{"description":"OK","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Notification"}}}},"401":{"description":"API response in case of unauthorized access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Unauthorized":{"$ref":"#/components/examples/UnauthorizedErrorExample"}}}}},"403":{"description":"API response in case of forbidden access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Forbidden":{"$ref":"#/components/examples/ForbiddenErrorExample"}}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKey":[]},{"Bearer":[]}]},"delete":{"tags":["Batch notifications (BETA)"],"summary":"(BETA) Delete a notification","description":"(BETA) Delete a notification by its id.","operationId":"deleteNotification","parameters":[{"name":"notificationId","in":"path","description":"Identifier that was auto-generated on notification creation and uniquely identifies the notification.","required":true,"schema":{"type":"string","minLength":1},"example":"NOTIFICATION-3fa85f64-5717-4562-b3fc-2c963f66afa6"},{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"responses":{"204":{"description":"No Content","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}}},"401":{"description":"API response in case of unauthorized access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Unauthorized":{"$ref":"#/components/examples/UnauthorizedErrorExample"}}}}},"403":{"description":"API response in case of forbidden access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Forbidden":{"$ref":"#/components/examples/ForbiddenErrorExample"}}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKey":[]},{"Bearer":[]}]}},"/batch/notifications/{notificationId}/test":{"get":{"tags":["Batch notifications (BETA)"],"summary":"(BETA) Test a notification","description":"(BETA) Test a notification with dummy parameters. This allows, to test the endpoint without letting a job run.","operationId":"testNotification","parameters":[{"name":"notificationId","in":"path","description":"Identifier that was auto-generated on notification creation and uniquely identifies the notification.","required":true,"schema":{"type":"string","minLength":1},"example":"NOTIFICATION-3fa85f64-5717-4562-b3fc-2c963f66afa6"},{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"responses":{"204":{"description":"No Content","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}}},"401":{"description":"API response in case of unauthorized access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Unauthorized":{"$ref":"#/components/examples/UnauthorizedErrorExample"}}}}},"403":{"description":"API response in case of forbidden access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Forbidden":{"$ref":"#/components/examples/ForbiddenErrorExample"}}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKey":[]},{"Bearer":[]}]}},"/health":{"get":{"tags":["API Information"],"summary":"Tests the basic health of the service.","operationId":"getHealth","parameters":[{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"responses":{"200":{"description":"Health response in case of success or failure.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/openapi":{"get":{"tags":["API Information"],"summary":"Retrieves the OpenAPI v3 specification.","description":"Retrieves the OpenAPI v3 specification for this service in YAML or JSON format based on the Accept header.\n\nUse Accept: text/yaml, application/vnd.oai.openapi, or application/openapi+yaml for YAML format.\nUse Accept: application/json or application/openapi+json for JSON format.","operationId":"getOpenApi","parameters":[{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"responses":{"200":{"description":"The OpenAPI v3 specification in the requested format","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"text/yaml":{"schema":{"type":"string"}},"application/vnd.oai.openapi":{"schema":{"type":"string"}},"application/openapi+yaml":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"application/openapi+json":{"schema":{"type":"string"}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/version":{"get":{"tags":["API Information"],"summary":"Retrieves API version information.","operationId":"getVersion","parameters":[{"name":"X-Request-ID","in":"header","description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}],"responses":{"200":{"description":"Version of the API","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionResponse"}}}},"401":{"description":"API response in case of unauthorized access.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"Unauthorized":{"$ref":"#/components/examples/UnauthorizedErrorExample"}}}}},"default":{"description":"API response in case of errors.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/X-Correlation-ID"},"X-Request-ID":{"$ref":"#/components/headers/X-Request-ID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"ApiKey":[]},{"Bearer":[]}]}}},"components":{"schemas":{"AuthErrorResponse":{"description":"Response on Authorization Error","properties":{"error":{"type":"string","description":"Human-readable error"},"error_description":{"type":"string","description":"Human-readable error description"}},"required":["error","error_description"]},"DataVersion":{"type":"object","description":"Version of a specific data set.","properties":{"name":{"type":"string","description":"Identifies a data set, for example, a HRN, or a service specific identifier."},"version":{"type":"string","description":"The current version of the data set."}},"required":["name","version"]},"ErrorResponse":{"type":"object","description":"Response in case of error.","properties":{"title":{"type":"string","description":"Human-readable error description.","example":"Input data failed validation"},"status":{"type":"integer","format":"int32","description":"HTTP status code.","example":400},"code":{"type":"string","description":"Error code.","example":"Exxxxxx"},"cause":{"type":"string","description":"Human-readable explanation for the error.","example":"The input data in question does not comply with validation rules"},"action":{"type":"string","description":"Human-readable description of the action that can be taken to correct the error.","example":"Provide validated input"},"correlationId":{"type":"string","description":"Auto-generated id that uniquely identifies the request.","example":"4199533b-6290-41db-8d79-edf4f4019a74"}},"required":["action","cause","code","correlationId","status","title"]},"HealthResponse":{"type":"object","description":"Returns the health of the service","properties":{"status":{"type":"string","default":"fail","description":"Health status of the service:\n\n* `ok` - the service is operating normally\n* `fail` - the service is currently encountering a failure","enum":["ok","fail"]}}},"JobDetailResponse":{"type":"object","description":"Detailed job information.","properties":{"id":{"type":"string","description":"Identifier that was auto-generated on job creation and uniquely identifies this job.","example":"JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6"},"serviceHrn":{"type":"string","description":"ID of the Service the job is executed against.","example":"hrn:here:service::olp-here:search-geocode-7"},"tag":{"type":"string","description":"Denotes one or more jobs and can be used as a filter in some job operations.","example":"my-job-tag"},"billingTags":{"type":"array","description":"Tags for billing operation. Can be up to 6 tags, no duplicates.","items":{"type":"string"},"uniqueItems":true},"status":{"type":"string","description":"The current status of the job.","enum":["submitted","queued","pending","inProgress","completed","stopped","deleted","failure"],"example":"inProgress"},"href":{"type":"string","description":"Link to obtain the details and status of this job","example":"https://<endpoint-url>/jobs/JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6"},"created":{"type":"string","format":"date-time","description":"Timestamp at which the job was created."},"started":{"type":"string","format":"date-time","description":"Timestamp at which the job started."},"ended":{"type":"string","format":"date-time","description":"Timestamp at which the job ended."},"records":{"$ref":"#/components/schemas/JobRecords"},"resultsHref":{"type":"string","description":"Link to obtain the results of this job","example":"https://<endpoint-url>/jobs/JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6/results"},"errorsHref":{"type":"string","description":"Link to obtain the errors of this job","example":"https://<endpoint-url>/jobs/JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6/errors"},"outputType":{"type":"string","description":"Output Mime Type for the results of this job","example":"csv"},"notificationIds":{"type":"array","description":"The notifications that are called at the end of a job.","items":{"type":"string"}}},"required":["created","id","serviceHrn","status"]},"JobRecords":{"type":"object","description":"Information on the Records within a particular job.","properties":{"total":{"type":"integer","format":"int32","description":"Total number of records in the job.","example":10000},"valid":{"type":"integer","format":"int32","description":"Number of valid records in the job.","example":9000},"invalid":{"type":"integer","format":"int32","description":"Number of invalid records in the job.","example":1000},"processed":{"type":"integer","format":"int32","description":"Number of records in the job that have been processed.","example":6000},"pending":{"type":"integer","format":"int32","description":"Number of records in the job that are still pending.","example":3000},"succeeded":{"type":"integer","format":"int32","description":"Number of records in the job that have successfully completed.","example":5500},"failed":{"type":"integer","format":"int32","description":"Number of records in the job that failed to complete successfully.","example":500}}},"JobResponse":{"type":"object","description":"Basic job information","properties":{"id":{"type":"string","description":"Identifier that was auto-generated on job creation and uniquely identifies this job.","example":"JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6"},"serviceHrn":{"type":"string","description":"ID of the Service the job is executed against.","example":"hrn:here:service::olp-here:search-geocode-7"},"tag":{"type":"string","description":"Denotes one or more jobs and can be used as a filter in some job operations.","example":"my-job-tag"},"billingTags":{"type":"array","description":"Tags for billing operation. Can be up to 6 tags, no duplicates.","items":{"type":"string"},"uniqueItems":true},"status":{"type":"string","description":"The current status of the job.","enum":["submitted","queued","pending","inProgress","completed","stopped","deleted","failure"],"example":"inProgress"},"href":{"type":"string","description":"Link to obtain the details and status of this job","example":"https://<endpoint-url>/jobs/JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6"}},"required":["id","serviceHrn","status"]},"JobsDeletedResponse":{"type":"object","description":"Listing of all the jobs that were deleted.","properties":{"total":{"type":"integer","format":"int32","description":"The number of jobs that were deleted","example":2},"jobIds":{"type":"array","description":"Identifiers of the jobs that were deleted","items":{"type":"string"}}},"required":["jobIds","total"]},"Notification":{"type":"object","description":"Notification hook that is called on jobs completion.","properties":{"id":{"type":"string","description":"Identifier that was auto-generated on notification creation and uniquely identifies this notification.","example":"NOTIFICATION-3fa85f64-5717-4562-b3fc-2c963f66afa6","readOnly":true},"type":{"type":"string","default":"webHook","description":"The type of the notification.","enum":["webHook"],"example":"webHook"},"lastUsedTime":{"type":"string","format":"date-time","description":"The timestamp when the notification was last used.","readOnly":true},"config":{"type":"object","additionalProperties":false,"description":"To configure a notification, the **type** as well as the the **config** property needs to be defined. Each type requires individual properties as listed below.\n\n### `webHook`\nFor the notification of the type `webHook` only a **url** parameter is required. This URL is called via a GET request, after the job is completed.\nTo individualize the request, property placeholders in the URL are substituted if surrounded by '${' and '}' These placeholders can be in the path or a query parameter.\n\nAvailable properties are:\n - JOB_ID\n - JOB_NAME\n - JOB_STATUS\n - JOB_OUTPUT_TYPE\n - JOB_RECORDS_SUCCEEDED\n - JOB_RECORDS_FAILED\n - JOB_RECORDS_TOTAL\n - JOB_RECORDS_VALID\n - JOB_RECORDS_INVALID\n\nAn example for the url property would be: 'https://myPublicDomain.de?jobId=${JOB_ID}&status=${JOB_STATUS}'","example":{"url":"https://myPublicDomain.de?jobId=${JOB_ID}&status=${JOB_STATUS}"}}},"required":["config","id","type"]},"PaginatedJobDetailResponse":{"type":"object","description":"A page of detailed job Information","properties":{"limit":{"type":"integer","format":"int32","description":"Maximum number of items per Page","example":100},"count":{"type":"integer","format":"int32","description":"Number of items in this Page","example":1},"items":{"type":"array","items":{"$ref":"#/components/schemas/JobDetailResponse"}}},"required":["count"]},"VersionResponse":{"type":"object","description":"Returns the versions of the service components.","properties":{"apiVersion":{"type":"string","description":"The current version of the API.","example":"v7"},"serviceVersion":{"type":"string","description":"The current version of the service.","example":"7.0.17"},"dataVersions":{"type":"array","description":"Returns the versions of data sets used by the service.","items":{"$ref":"#/components/schemas/DataVersion"}}},"required":["apiVersion","serviceVersion"]}},"examples":{"UnauthorizedErrorExample":{"value":{"error":"Unauthorized","error_description":"No credentials found"}},"ForbiddenErrorExample":{"value":{"error":"Forbidden","error_description":"These credentials do not authorize access"}},"JobNotFoundErrorExample":{"value":{"title":"Job not found","status":404,"code":"E6004041","cause":"Job with the specified ID could not be found","action":"Verify the job ID and try again","correlationId":"4199533b-6290-41db-8d79-edf4f4019a74"}},"JobResultsUnavailableErrorExample":{"value":{"title":"Results unavailable","status":404,"code":"E6004042","cause":"The results of the job are unavailable at this time","action":"Check that the job has completed and try again","correlationId":"4199533b-6290-41db-8d79-edf4f4019a74"}},"JobInputUndefinedErrorExample":{"value":{"title":"Input for the the job is not defined","status":404,"code":"E6004044","cause":"Input for the job is not available","action":"Add the input to the job and try again","correlationId":"4199533b-6290-41db-8d79-edf4f4019a74"}},"ServiceUnsupportedErrorExample":{"value":{"title":"Service not found or is unsupported","status":404,"code":"E6004043","cause":"The Service with the specified HRN could not be found or is not supported at this time","action":"Check that the Service HRN was entered correctly","correlationId":"4199533b-6290-41db-8d79-edf4f4019a74"}},"JobIdInvalidErrorExample":{"value":{"title":"ID argument invalid","status":400,"code":"E6004001","cause":"The ID provided could not be parsed as a valid job ID","action":"Correct the ID to conform to job ID specifications","correlationId":"4199533b-6290-41db-8d79-edf4f4019a74"}},"ArgumentExceedsMaxLengthErrorExample":{"value":{"title":"Argument exceeds maximum length limit","status":400,"code":"E6004002","cause":"The argument exceeds the maximum supported character length (256 characters)","action":"Shorten the argument to match length requirements","correlationId":"4199533b-6290-41db-8d79-edf4f4019a74"}},"InputExceedsMaxSizeErrorExample":{"value":{"title":"Input exceeds maximum size limit","status":400,"code":"E6004003","cause":"The input exceeds the maximum allowed size of 1GB","action":"Trim the input or split the job into smaller jobs","correlationId":"4199533b-6290-41db-8d79-edf4f4019a74"}},"InputEmptyErrorExample":{"value":{"title":"Input empty or invalid","status":400,"code":"E6004004","cause":"The job's input could not be validated or is empty","action":"Provide valid input to the job","correlationId":"4199533b-6290-41db-8d79-edf4f4019a74"}},"CharacterDelimiterUnsupportedErrorExample":{"value":{"title":"Delimiter character is unsupported","status":400,"code":"E6004005","cause":"The supplied character string is not supported as a delimiter for output/input","action":"Provide a single character delimiter that can be used to delimit output/input","correlationId":"4199533b-6290-41db-8d79-edf4f4019a74"}},"UnmodifiableJobErrorExample":{"value":{"title":"Job cannot be modified","status":400,"code":"E6004006","cause":"The job cannot be modified because it is currently running","action":"Stop the job and then try modifying the job again","correlationId":"4199533b-6290-41db-8d79-edf4f4019a74"}},"MaxConcurrentJobsErrorExample":{"value":{"title":"Too many concurrent jobs running","status":429,"code":"E6004291","cause":"You have exceeded the number of jobs you may run concurrently","action":"Stop or wait for your existing jobs to complete and then try starting the job again","correlationId":"4199533b-6290-41db-8d79-edf4f4019a74"}},"GeocoderJobSubmittedExample":{"value":{"id":"JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6","serviceHrn":"hrn:here:service::olp-here:search-geocode-7","tag":"my-geocoder-job","billingTags":["billingTagGeocoder3","billingTagGeocoder2","billingTagGeocoder1"],"status":"submitted","href":"https://<endpoint-url>/jobs/JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6"}},"ReverseGeocoderJobSubmittedExample":{"value":{"id":"JOB-88b5b0ff-0479-4380-8af7-6af809e8b335","serviceHrn":"hrn:here:service::olp-here:search-revgeocode-7","tag":"my-reverse-geocoder-job","billingTags":["billingTagRevGeocoder1","billingTagRevGeocoder2","billingTagRevGeocoder3"],"status":"submitted","href":"https://<endpoint-url>/jobs/JOB-88b5b0ff-0479-4380-8af7-6af809e8b335"}},"GeocoderJobPendingExample":{"value":{"id":"JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6","serviceHrn":"hrn:here:service::olp-here:search-geocode-7","tag":"my-geocoder-job","billingTags":["billingTagGeocoder3","billingTagGeocoder2","billingTagGeocoder1"],"status":"pending","href":"https://<endpoint-url>/jobs/JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6"}},"ReverseGeocoderJobPendingExample":{"value":{"id":"JOB-88b5b0ff-0479-4380-8af7-6af809e8b335","serviceHrn":"hrn:here:service::olp-here:search-revgeocode-7","tag":"my-reverse-geocoder-job","billingTags":["billingTagRevGeocoder1","billingTagRevGeocoder2","billingTagRevGeocoder3"],"status":"pending","href":"https://<endpoint-url>/jobs/JOB-88b5b0ff-0479-4380-8af7-6af809e8b335"}},"GeocoderJobStoppedExample":{"value":{"id":"JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6","serviceHrn":"hrn:here:service::olp-here:search-geocode-7","tag":"my-geocoder-job","billingTags":["billingTagGeocoder3","billingTagGeocoder2","billingTagGeocoder1"],"status":"stopped","href":"https://<endpoint-url>/jobs/JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6"}},"ReverseGeocoderJobStoppedExample":{"value":{"id":"JOB-88b5b0ff-0479-4380-8af7-6af809e8b335","serviceHrn":"hrn:here:service::olp-here:search-revgeocode-7","tag":"my-reverse-geocoder-job","billingTags":["billingTagRevGeocoder1","billingTagRevGeocoder2","billingTagRevGeocoder3"],"status":"stopped","href":"https://<endpoint-url>/jobs/JOB-88b5b0ff-0479-4380-8af7-6af809e8b335"}},"GeocoderJobDeletedExample":{"value":{"id":"JOB-3fa85f64-5717-4562-b3fc-2c963f66afa6","serviceHrn":"hrn:here:service::olp-here:search-geocode-7","status":"deleted"}},"WebHookNotificationExample":{"value":{"id":"NOTIFICATION-3fa85f64-5717-4562-b3fc-2c963f66afa6","type":"webHook","config":{"url":"https://myPublicDomain.de?jobId=${JOB_ID}&status=${JOB_STATUS}"}}},"GeocoderJobOutput":{"value":"recId|seqNumber|seqLength|position|title\n0001|1|1|(52.5308609,13.3846903)|Invalidenstraße 116, 10115 Berlin, Deutschland\n0002|1|1|(50.1619301,8.5336103)|Am Kronberger Hang 8, 65824 Schwalbach, Deutschland\n0003|1|1|(41.8843193,-87.6387711)|425 W Randolph St, Chicago, IL 60606, United States\n0004|1|1|(42.3622513,-71.0802994)|1 Main St, Cambridge, MA 02142, United States\n0005|1|1|(37.376339,-122.03405)|200 S Mathilda Ave, Sunnyvale, CA 94086, United States"},"GeocoderJobInputWithHeader":{"value":"recId|q|in|lang|limit\n001|Invalidenstraße 116 10115 Berlin|DEU|de-DE|20\n002|Am Kronberger Hang 8 65824 Schwalbach|DEU|de-DE|20\n003|425 W Randolph St Chicago IL 60606|USA|en-US|20\n004|One Main Street Cambridge MA 02142|USA|en-US|20\n005|200 S Mathilda Ave Sunnyvale CA 94086|USA|en-US|20"},"GeocoderJobInputAsURLQuery":{"value":"q=Invalidenstraße 116 10115 Berlin&in=countryCode:DEU&lang=de-DE&limit=20\nq=Am Kronberger Hang 8 65824 Schwalbach&in=countryCode:DEU&lang=de-DE&limit=20\nq=425 W Randolph St Chicago IL 60606&in=countryCode:USA&lang=en-US&limit=20\nq=One Main Street Cambridge MA 02142&in=countryCode:USA&lang=en-US&limit=20\nq=200 S Mathilda Ave Sunnyvale CA 94086&in=countryCode:USA&lang=en-US&limit=20"},"ReverseGeocoderJobInputWithHeader":{"value":"recId|at|lang|limit\n001|52.5308609,13.3846903|de-DE|1\n002|50.1619301,8.5336103|de-DE|1\n003|41.8843193,-87.6387711|en-US|1\n004|42.3622513,-71.0802994|en-US|1\n005|37.376339,-122.03405|en-US|1"},"ReverseGeocoderJobInputAsURLQuery":{"value":"at=52.5308609,13.3846903&limit=1&lang=en-US\nat=50.1619301,8.5336103&limit=1&lang=en-US\nat=41.8843193,-87.6387711&limit=1&lang=en-US\nat=42.3622513,-71.0802994&limit=1&lang=en-US\nat=37.376339,-122.03405&limit=1&lang=en-US"},"LookupJobInputWithHeader":{"value":"recId|id\n001|here:af:streetsection:tVuvjJYhO86yd5jk1cmzNB:CgcIBCCE59BeEAEaAzExNg\n002|here:af:streetsection:6cjWtEIO2t07E.pKRVV5bA:CgcIBCCa46pZEAEaATgiCEhpbGxzaXRl\n003|here:af:streetsection:hdZ6xBRUraY46IQZCqZidD:CgcIBCDMlOElEAEaAzQyNQ\n004|here:af:streetsection:k-3ojKsslOuU0B1PF4J4HD:CgcIBCCq3cJGEAEaATE\n005|here:af:streetsection:otB53KK-9vZXGNGL.uhpFD:CgcIBCD3n4EPEAEaAzIwMA"},"LookupJobInputAsURLQuery":{"value":"id=here:af:streetsection:tVuvjJYhO86yd5jk1cmzNB:CgcIBCCE59BeEAEaAzExNg\nid=here:af:streetsection:6cjWtEIO2t07E.pKRVV5bA:CgcIBCCa46pZEAEaATgiCEhpbGxzaXRl\nid=here:af:streetsection:hdZ6xBRUraY46IQZCqZidD:CgcIBCDMlOElEAEaAzQyNQ\nid=here:af:streetsection:k-3ojKsslOuU0B1PF4J4HD:CgcIBCCq3cJGEAEaATE\nid=here:af:streetsection:otB53KK-9vZXGNGL.uhpFD:CgcIBCD3n4EPEAEaAzIwMA"}},"headers":{"X-Correlation-ID":{"description":"Auto-generated ID, which uniquely identifies the request, available in the response.\n When contacting support with an inquiry regarding a specific request, provide the value of this header which will help troubleshooting the issue.","schema":{"type":"string"}},"X-Request-ID":{"description":"User-provided token that can be used to trace a request or a group of requests sent to the service.","schema":{"type":"string"}}},"securitySchemes":{"ApiKey":{"type":"apiKey","description":"A key generated specifically to authenticate API requests. For more information on how to get an API key, see the\n API key used to authorize requests. For more information, see\n [Identity & Access Management Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/README.html)","name":"apiKey","in":"query"},"Bearer":{"type":"http","description":"A token obtained from a separate endpoint using client credentials and an OAuth 1.0a HMAC-SHA256 signed request.\n For more information on how to get a bearer token, see the [Identity & Access Management Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/README.html)","scheme":"bearer","bearerFormat":"JWT"}}}}