HERE Batch API v7

{"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":"#/c

# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/here/refs/heads/main/openapi/here-geocoding-batch-v7-openapi.yml