GuidesAPI Reference
Guides
  1. Batch API v7 Developer Guide
  2. Tutorials

Get job results

The user wants to download the results and errors of a finished job.

Request

This GET request below uses the jobId from an earlier request to retrieve the results and errors.

You need to use the jobId from your own request.

GET https://batch.search.hereapi.com/v7/batch/jobs/<jobId>/results
GET https://batch.search.hereapi.com/v7/batch/jobs/<jobId>/errors

With cURL assuming jobId is in environment from earlier request. Variable YOUR_API_KEY has also to be set:

curl --request 'GET' \
  "https://batch.search.hereapi.com/v7/batch/jobs/${jobId}/results?apiKey=${YOUR_API_KEY}" \
  --header 'accept: text/plain'
curl --request 'GET' \
  "https://batch.search.hereapi.com/v7/batch/jobs/${jobId}/errors?apiKey=${YOUR_API_KEY}" \
  --header 'accept: text/plain'

Response

The response is a plain text file, either in CSV or in JSONL (Alpha) format.

For details on how to select an output format at job creation time, please see Request parameters for job submission.

For details on requesting a compressed file as response, see Gzip compression.

📘

Note

If a job has no results (only errors) or no errors (all successful), the related href property in job status is empty. Invoking the endpoint anyway will result in a 204 response with empty body. Invoking the endpoint before the job is completed, will result in a 404 response.

CSV Output

For information on how to understand the CSV response, see Reading batch request output.

Example output:

recId|seqNumber|seqLength|positionLat|positionLng|addressLabel|addressHouseNumber|addressStreet|addressDistrict|addressCity|addressPostalCode|addressCounty|addressState|addressCountryCode
0001|1|1|52.5308609|13.3846903|Invalidenstraße 116, 10115 Berlin, Deutschland|116|Invalidenstraße|Mitte|Berlin|10115|Berlin|Berlin|DEU
0002|1|1|50.1619301|8.5336103|Am Kronberger Hang 8, 65824 Schwalbach, Deutschland|8|Am Kronberger Hang||Schwalbach|65824|Main-Taunus-Kreis|Hessen|DEU
0003|1|1|41.8843193|-87.6387711|425 W Randolph St, Chicago, IL 60606, United States|425|W Randolph St|West Loop|Chicago|60606|Cook|IL|USA
0004|1|1|42.3622513|-71.0802994|1 Main St, Cambridge, MA 02142, United States|1|Main St|East Cambridge|Cambridge|02142|Middlesex|MA|USA

JSONL output

The JSONL response is quite simple to understand.

In each row there is a single JSON object structure containing a record id and all responses returned by the target service for that record id.

Therefore, the JSONL response can NOT be parsed as a whole, but must rather be parsed one line at a time.

The JSONL structure looks like this:

{"recId":"001","results":[{"title":"Invalidenstraße 116, 10115 Berlin, Deutschland","id":"here:af:streetsection:tVuvjJYhO86yd5jk1cmzNB:CgcIBCCE59BeEAEaAzExNg","resultType":"HOUSENUMBER","houseNumberType":"PA","address":{"label":"Invalidenstraße 116, 10115 Berlin, Deutschland","countryCode":"DEU","countryName":"Deutschland","stateCode":"BE","state":"Berlin","countyCode":"B","county":"Berlin","city":"Berlin","district":"Mitte","street":"Invalidenstraße","postalCode":"10115","houseNumber":"116"},"position":{"lat":52.53086,"lng":13.38469},"access":[{"lat":52.531,"lng":13.38461}],"mapView":{"west":13.38321,"south":52.52996,"east":13.38617,"north":52.53176},"scoring":{"queryScore":1.0,"fieldScore":{"city":1.0,"streets":[1.0],"houseNumber":1.0,"postalCode":1.0}}}]}
{"recId":"002","results":[{"title":"Am Kronberger Hang 8, Hillsite, 65824 Schwalbach am Taunus, Deutschland","id":"here:af:streetsection:6cjWtEIO2t07E.pKRVV5bA:CgcIBCCa46pZEAEaATgiCEhpbGxzaXRl","resultType":"HOUSENUMBER","houseNumberType":"PA","address":{"label":"Am Kronberger Hang 8, Hillsite, 65824 Schwalbach am Taunus, Deutschland","countryCode":"DEU","countryName":"Deutschland","stateCode":"HE","state":"Hessen","countyCode":"MTK","county":"Main-Taunus-Kreis","city":"Schwalbach am Taunus","district":"Schwalbach am Taunus","street":"Am Kronberger Hang","postalCode":"65824","houseNumber":"8","building":"Hillsite"},"position":{"lat":50.16193,"lng":8.53361},"access":[{"lat":50.16189,"lng":8.53346}],"mapView":{"west":8.53221,"south":50.16103,"east":8.53501,"north":50.16283},"scoring":{"queryScore":1.0,"fieldScore":{"city":1.0,"streets":[1.0],"houseNumber":1.0,"postalCode":1.0}}}]}
{"recId":"003","results":[{"title":"425 W Randolph St, Chicago, IL 60606-1515, United States","id":"here:af:streetsection:hdZ6xBRUraY46IQZCqZidD:CgcIBCDMlOElEAEaAzQyNQ","resultType":"HOUSENUMBER","houseNumberType":"PA","address":{"label":"425 W Randolph St, Chicago, IL 60606-1515, United States","countryCode":"USA","countryName":"United States","stateCode":"IL","state":"Illinois","county":"Cook","city":"Chicago","district":"West Loop","street":"W Randolph St","postalCode":"60606-1515","houseNumber":"425"},"position":{"lat":41.88432,"lng":-87.63877},"access":[{"lat":41.88449,"lng":-87.63877}],"mapView":{"west":-87.63998,"south":41.88342,"east":-87.63756,"north":41.88522},"scoring":{"queryScore":1.0,"fieldScore":{"state":1.0,"city":1.0,"streets":[1.0],"houseNumber":1.0,"postalCode":1.0}}}]}
{"recId":"004","results":[{"title":"1 Main St, Cambridge, MA 02142-1517, United States","id":"here:af:streetsection:k-3ojKsslOuU0B1PF4J4HD:CgcIBCCq3cJGEAEaATE","resultType":"HOUSENUMBER","houseNumberType":"PA","address":{"label":"1 Main St, Cambridge, MA 02142-1517, United States","countryCode":"USA","countryName":"United States","stateCode":"MA","state":"Massachusetts","county":"Middlesex","city":"Cambridge","district":"East Cambridge","street":"Main St","postalCode":"02142-1517","houseNumber":"1"},"position":{"lat":42.36225,"lng":-71.0803},"access":[{"lat":42.36195,"lng":-71.08012}],"mapView":{"west":-71.08152,"south":42.36135,"east":-71.07908,"north":42.36315},"scoring":{"queryScore":1.0,"fieldScore":{"state":1.0,"city":1.0,"streets":[1.0],"houseNumber":1.0,"postalCode":1.0}}}]}
{"recId":"005","results":[{"title":"200 S Mathilda Ave, Sunnyvale, CA 94086-6135, United States","id":"here:af:streetsection:otB53KK-9vZXGNGL.uhpFD:CgcIBCD3n4EPEAEaAzIwMA","resultType":"HOUSENUMBER","houseNumberType":"PA","address":{"label":"200 S Mathilda Ave, Sunnyvale, CA 94086-6135, United States","countryCode":"USA","countryName":"United States","stateCode":"CA","state":"California","county":"Santa Clara","city":"Sunnyvale","district":"Heritage District","street":"S Mathilda Ave","postalCode":"94086-6135","houseNumber":"200"},"position":{"lat":37.37634,"lng":-122.03405},"access":[{"lat":37.37641,"lng":-122.03445}],"mapView":{"west":-122.03518,"south":37.37544,"east":-122.03292,"north":37.37724},"scoring":{"queryScore":1.0,"fieldScore":{"state":1.0,"city":1.0,"streets":[1.0],"houseNumber":1.0,"postalCode":1.0}}}]}

Please note that there are no line breaks. The idea is to deliver a complete JSON object in a single line of output.

The following is the structure of the first line of the above response with line breaks added for readability:

{
    "recId": "001",
    "results": [
        {
            "title": "Invalidenstraße 116, 10115 Berlin, Deutschland",
            "id": "here:af:streetsection:tVuvjJYhO86yd5jk1cmzNB:CgcIBCCE59BeEAEaAzExNg",
            "resultType": "HOUSENUMBER",
            "houseNumberType": "PA",
            "address": {
                "label": "Invalidenstraße 116, 10115 Berlin, Deutschland",
                "countryCode": "DEU",
                "countryName": "Deutschland",
                "stateCode": "BE",
                "state": "Berlin",
                "countyCode": "B",
                "county": "Berlin",
                "city": "Berlin",
                "district": "Mitte",
                "street": "Invalidenstraße",
                "postalCode": "10115",
                "houseNumber": "116"
            },
            "position": {
                "lat": 52.53086,
                "lng": 13.38469
            },
            "access": [
                {
                    "lat": 52.531,
                    "lng": 13.38461
                }
            ],
            "mapView": {
                "west": 13.38321,
                "south": 52.52996,
                "east": 13.38617,
                "north": 52.53176
            },
            "scoring": {
                "queryScore": 1,
                "fieldScore": {
                    "city": 1,
                    "streets": [
                        1
                    ],
                    "houseNumber": 1,
                    "postalCode": 1
                }
            }
        }
    ]
}

On the top level of the returned object, there is a field recId containing the id of the corresponding input record.

On the same level, the field results will contain all results returned by Geocoder for the input record as a JSON array.

The array contains standard Geocoder JSON objects as would be returned by Geocoder service when queried directly.

For a detailed description of the Geocoder response object structure, please refer to Geocoder documentation.

Special case: No match

When the underlying service asked has not found a match for the input, the result is 'empty'.

Example output in CSV

recId|seqNumber|seqLength|position|title|id
001|1|1|||

Example output in JSONL

{"recId":"001","results":[]}

Errors

This is the errors report from Geocoding example, but in line 2 and 3 the country code (last column) is removed.

The columns are fix recId, errorCode and errorMessage. For more details see Reading job output.

recId|errorCode|errorMessage
InputLine_2|999|{"status":999,"recordId":"InputLine_2","title":"Illegal input line","cause":"The input line does not conform to given input format for job.","action":"Please check format for job record and resubmit in new job.","jobRecord":"0002|Am Kronberger Hang 8 65824 Schwalbach"}
InputLine_3|999|{"status":999,"recordId":"InputLine_3","title":"Illegal input line","cause":"The input line does not conform to given input format for job.","action":"Please check format for job record and resubmit in new job.","jobRecord":"0003|425 W Randolph St Chicago IL 60606"}

Related information

Updated 29 days ago