======================
GET /:country/listings
======================

Returns a set of `Listings`_ corresponding to the given filter.

It is possible to filter either by listing ID, phone number or address. It is
not possible to combine these filters.

URL Parameters
--------------

Common parameters:

.. list-table::
    :widths: 20 80

    * - | **limit**
        | Optional
      - | Maximum number of listings to return.
        | Defaults to 50 and cannot be greater than 50.
        | Example: ``limit=10``

Searching by IDs:

.. list-table::
    :widths: 20 80

    * - | **ids**
        | *Required*
      - | A list of comma separated listings IDs.
        | Example: ``ids=1,5,10``

Searching by phone number:

.. list-table::
    :widths: 20 80

    * - | **phone**
        | *Required*
      - | Phone number to filter by in `E.164`_ format.
        | Example: ``phone=+38511234567``

Searching by address:

.. list-table::
    :widths: 20 80

    * - | **street**
        | *Required*
      - | Street name wihtout the house number.
        | Example: ``street=Müllerstraße``
    * - | **place**
        | *Required*
      - | Place name.
        | Example: ``place=München``
    * - | **postCode**
        | *Required*
      - | The post code.
        | Example: ``street=80469``
    * - | **number**
        | Optional
      - | The house number
        | Example: ``number=40``


Address search is not case sensitive. The ``*`` wildcard can be used, which will
match zero or more characters. For example ``place=Mü*`` will match "München",
"Münster", etc.

Responses
---------

On success returns **HTTP 200 OK** with the folowing data:

============= ===============================================
 Key           Content / Description
============= ===============================================
 numFound      The number of listings matching the filter.
 numReturned   The number of listings returned, can be less
               than ``numFound`` if it exceeds the limit
               of 50 listings.
 listings      An array of `Listings`_ (can be empty).
============= ===============================================

On error returns an `Error`_ object.

Examples
--------

Searching by phone:

.. code-block:: text

    GET http://api.opendi.de/de/listings?phone=%2B4989189476626

Searching by address:

.. code-block:: text

    GET http://api.opendi.de/de/listings?street=Müllerstraße&place=München&postCode=80469&number=40

Sample result:

**HTTP 200 OK**

.. code-block:: javascript

    {
        "numFound":1,
        "numReturned":1,
        "listings":[
            {
                "id": "5194891",
                "name": "Opendi AG",
                "address": "40 Müllerstr.",
                "zip": "80469",
                "place": "München",
                "country_code": "DE",
                "latitude": null,
                "longitude": null,
                "keywords": [],
                "description": null,
                "emails": [
                    {
                        "id": "1457387",
                        "address": "a.stahl@opendi.com"
                    }
                ],
                "phones": [
                    {
                        "id": "7358891",
                        "type": "landline",
                        "number": "+498001055105"
                    },
                    {
                        "id": "7364231",
                        "type": "landline",
                        "number": "+4989189476620"
                    },
                    {
                        "id": "7364232",
                        "type": "fax",
                        "number": "+4989189476626"
                    }
                ],
                "url": "http://muenchen.de-eu-staging.opendi.com/5194891.html",
                "hours": {
                    "monday": [
                        {
                            "start": "09:00:00",
                            "end": "17:00:00"
                        }
                    ],
                    "tuesday": [
                        {
                            "start": "09:00:00",
                            "end": "17:00:00"
                        }
                    ],
                    "wednesday": [
                        {
                            "start": "09:00:00",
                            "end": "17:00:00"
                        }
                    ],
                    "thursday": [
                        {
                            "start": "09:00:00",
                            "end": "17:00:00"
                        }
                    ],
                    "friday": [
                        {
                            "start": "09:00:00",
                            "end": "17:00:00"
                        }
                    ],
                    "saturday": [],
                    "sunday": []
                },
                "images": [],
                "links": [
                    {
                        "id": "1457386",
                        "type": "website",
                        "url": "www.stadtbranchenbuch.com"
                    },
                    {
                        "id": "1458640",
                        "type": "googleplus",
                        "url": "https://plus.google.com/118150864364347134043/"
                    }
                ],
                "categories": [
                    {
                        "id": "58",
                        "name": "Bestatter"
                    }
                ],
                "active": true
            }
        ]
    }

.. _E.164: http://en.wikipedia.org/wiki/E.164
.. _Listing: ./../models.html#listing
.. _Listings: ./../models.html#listing
.. _Error: ./../models.html#error