Find Nearest Points

With this endpoint you can retrieve a list of your points in Atlas sorted by closest to a given point of origin. A correct point of origin is any valid postal code or locality in the Nordic countries.

Remember to specify the maximum number of points you want to retrieve and if you only want to consider a filtered subset of your points, i.e. only points with a certain custom_field value.

URL¶

POST https://api.geposit.se/1.1/find/nearest/points

Mandatory header parameters¶

• x-api-key (String) This is your API-key and should be included in the header.

Mandatory POST parameters¶

• query (String) Should contain either a valid postalcode or a locality that you want to use as point of origin. The API assumes that the postalcode/locality is correctly formatted and will only return limited error codes if it is incorrect. For help in validating that the postalcode is correct, see Valid API.

• country_code (String) The country code of the postalcode/locality. The following country codes are supported:

  • se (Sweden)
  • no (Norway)
  • dk (Denmark)
  • fi (Finland)

• limit (Numeric value) The number of points you want to retrieve. (Maximum 100). Use a limit that suits your needs and enjoy optimal performance!

Optional POST parameters¶

• Attribute filtering/conditioning (String) The following operands can be used to filter for specific values.

Example: Find nearest points to postalcode 12947 where 'ecommerce' attribute (a custom_field) is true.

/find/nearest/points?country_code=se&query=12947&ecommerce[eq]=1&limit=10

Example Request¶

curl -X POST -H "X-api-key: {API_KEY}" https://api.geposit.se/1.1/find/nearest/points -d "country_code=se&query=16471&limit=10"

client()->post("find/nearest/points", [
    "query" => [
        "query" => "16471",
        "country_code" => "se",
        "limit" => 10
    ],
    "headers" => [
        "x-api-key" => "your-api-key"
    ],
]);

Response¶

The response will be in JSON format. Every response comes with a status flag (Integer) where:

• status = 0 - Incoming postalcode/locality is invalid / generic error.
• status = 1 - Incoming postalcode/locality is valid and exists.

Valid response¶

• points (Array) Array that will contain zero or more members, each containing point objects (with at least an point_id and a name). An empty array indicates that no points where found that matched the given request parameters/filters.

• origin (Array) Array that will contain the x_lon and y_lat of the origin point where distances has been measured from. If postalcode was provided in the 'query' parameter - this array will contain the centroid of the postalcode. If locality was provided in the 'query' parameter - this array will contain the centroid of the locality.

• point_id (Integer) The unique identifier of the point. This id can be used to fetch more detailed information about the point, using the get point details endpoint.

• name (String) The name of the point.

• postalcode (String) The postalcode number.

• locality (String) The locality to which the postalcode belongs.

• x_lon (float) The X / Longitude position (in WGS84 - EPSG:4326)

• y_lat (float) The Y / Latitude position (in WGS84 - EPSG:4326)

{
    "count": 5,
    "origin": {
        "postalcode": "11215",
        "locality": "Stockholm",
        "x_lon": 18.07376297441,
        "y_lat": 59.331613376725
    },
    "points": [
        {
            "point_id": 2471,
            "name": "My store name 1",
            "address": "Storgatan 12 E",
            "postalcode": "11217",
            "locality": "Stockholm",
            "x_lon": 18.071217815363,
            "y_lat": 59.345051612136,
            "id":"CUST-23923",
            "phone": "+46 123 456",
            "ecommerce": 1
        },
        {
            "point_id": 5239,
            "name": "My store name 2",
            "address": "Norrvägen 4",
            "postalcode": "11342",
            "locality": "Stockholm",
            "x_lon": 18.02920349023,
            "y_lat": 59.37029340933,
            "id":"CUST-24032",
            "phone": "+46 654 321",
            "ecommerce": 0
        }
    ( {... } other points that matched the query )
    ]
}

{
    "status": 1,
    "count": 0,
    "origin": {
        "postalcode": "11215",
        "locality": "Stockholm",
        "x_lon": 18.07376297441,
        "y_lat": 59.331613376725
    },
    "points": []
}

Invalid response¶

{
    "status": 0,
    "error": "Incorrect postalcode"
}

{
    "status": 0,
    "error": "Country code '{cc}' is not supported"
}

{
    "status": 0,
    "error": "Generic error"
}