Suggestion server

The suggestion server is a search engine for filters, and translates names and urls to ids the API understands.

It is designed to be used interactively and as a companion to the search API. Users can start to type the name of a site or a country, and get suggestions for filters matching the terms back. The response contains useful data for building interactive UIs, like highighting information about any of the matches.

The suggestion server is also a more general bridge between urls and names in natural language and abstracted ids used by the API. Depending on the users language, the same country can be refered to as either Germany or Deutschland. With the suggestion server, you search in your language of choice, and get, among other things, the language agnostic ids back.

Note that it can also do the inverse, return names based on ids.

Filter types

The suggestion server supports a selected number of filters, and the search terms will match the names and urls of whatever they refer to. Language filters match names of languages, geo filters match geographical regions, so passing France will in general return a language filter and a geo filter among its top results.

Looking at what the various filters refer to, thus gives some idea of what to expect in the results:

  • site

    Site filters match particular providers of content, like The Guardian.

    Since the providers often have a website, and a corresponding url, the url can also be matched, like theguardian.com.

  • lang

    Language filters match languages, like English.

  • geo

    Geographic filters match regions, like a continent, a country like England, and sometimes even at county level.

  • rank

    Ranks are categories ordered 1 through 5. The rank is a function, among other things, of a sites popularity and how often they publish articles, 1 being the most reputable.

  • media

    Media filters match media types, like print and web.

  • content

    Content filters match the kind of content provider, like the government, an individual, editorial media or a local newspaper.

  • timePeriod

    A time interval.

  • ent

    An entity id.

  • topic

    A topic id.

Searching

The suggestion server is queried at the suggest endpoint: 

https://suggest.api.opoint.com/suggest/<locale>/<mode>/<results_count>/<offsets>/0/<access_group>/<selected_filters>/<search_term>

Path parameters

  • link locale string

    Locale determining the search term and response language.

    Also accepts a timezone offset in UTC format. Add a colon to separate them, like en_GB_1:UTC+2.

    It supports choosing which sorting you want as well, the number en_GB_<sorting> can be used. By setting this to 1, you get the default sorting for the locale (language) you have requested.

  • link results_count int

    Maximum number of results for single mode. It will cap the number of results if there are not enough suggestions matching the search term.

    Number of suggestions of each filter type for multiple mode. If there are not enough matching results for a filter type, the list will be filled with non-matching filters with the highest priority.

  • link offsets string

    Filter and pagination settings, either 0 to turn off, or on the format type:index,type:index.

    If enabled, the results will only contain filters of the mentioned types.

    The index controls the offset. type:0 returns filters from the start of the list. The next_offset field in the response contains the offset settings needed to get the next filters in the list.

  • link access_group string

    This is divided into two integers, like <access_group>:<filter_types>.

    The access_group filters suggestions with given access. Set to 2147483647 to show all suggestions, regardless of access restrictions. Passing the users access group value will only show suggestions the user can actually view.

    The filter_type selects which filters to show suggestions for. If you want to look at sublists, the action field in the previous response should be used here.

    The number is a bitstring, where each bit indicates a filter type:

    • lang: 4
    • site: 64
    • geo: 128
    • timePeriod: 1024
    • ent: 65536
    • topic: 131072
    • media: 16777216
    • content: 67108864
    • rank: 2147483648

    To get suggestions for multiple filters, you can do a bitwise or of the numbers you are interested in. For example 64 | 4 = 68, so sending 68 will return suggestions for sites and languages

    If you only send one number, that will be interpreted as the access_group. And there will be returned suggestions for all filters.

  • link selected_filters string

    Filters to narrow the search results, on the same format as the search API.

    If this is set to nometa, no filtering will be done.

  • link search_term string

    A filter search term, like the name of a country or a language.

Examples

Basic request single mode
https://suggest.api.opoint.com/suggest/en_GB_1/single/5/0/0/2147483647/nometa/new%20york
Basic request multiple mode
https://suggest.api.opoint.com/suggest/en_GB_1/multiple/5/0/0/2147483647/nometa/new%20york
Search only among sites
https://suggest.api.opoint.com/suggest/en_GB_1/single/5/site:0/0/2147483647/nometa/new%20york

Response

The response contains a list of the matching filters along with information useful for display, such as highlighting information and localized names, with the results grouped depending on the mode. There are also some additional fields useful for pagination.

For single mode the list of filters are added to results field. For multiple mode the results are added to fields equal with the filter types name, as shown in the examples.

Response

  • link results list of objects

    List of information about matching filters. For multiple mode this field is replaced by lists with the filter types names.

    • link results[].type string

      Filter type. Use this if you want to use the item some other place, like this <type>:<id>.

    • link results[].typeName string

      Localized name of the filter type.

    • link results[].id string

      Filter value.

      If the type is site, some items have their id prefixed with 00. These are source-ids and not site-ids. You most likely don't have to worry about this, as most other systems automatically translates these for you.

    • link results[].name string

      Localized name of the filter value.

    • link results[].url string

      URL of the site if the type is site.

    • link results[].rank string

      Rank id of the site if the type is site.

    • link results[].meta string

      Language code of the site if type is site.

    • link results[].lang string
    • link results[].mo string

      Information about which of the words in the search term matched and where.

      Returns a string with one digit for each word in the search term. Each digit convey information about what the word in the search term matched. 0 means no match, 1 means match in name and 2 means match in the url. Entries added to fill up the list return n/a

    • link results[].match string or missing

      mo, but any word apart from the last in the search term must be a full match. Searching for n york will return 01 in match but 11 in mo for New York.

      Omitted if the entry is only there to fill up the list.

    • link results[].hl string or missing

      Highlighting information about matches to the `name. Only added if there is a match.

    • link results[].hlu string or missing

      Highlighting information about matches to the url. Only added if there is a match.

      On the same format as hl.

    • link results[].weight int
    • link results[].accessGroup int or missing

      Access needed to view the item.

  • link hits int

    Number of results returned for single mode. 0 for multiple mode.

  • link next_offset string

    Pagination cursor.

  • link tokens int
  • link time(ms) int
  • link warnings string

Examples

Example response single mode
{
  "results": [
    {
      "id": "1372",
      "name": "New York",
      "url": "",
      "accessGroup": 1,
      "type": "geo",
      "lang": "",
      "meta": "",
      "mo": "11",
      "match": "11",
      "hl": "0-2,4-7",
      "weight": 1575336,
      "rank": "",
      "typeName": "From"
    },
    {
      "id": "172,330084",
      "name": "New York Post",
      "url": "https://nypost.com",
      "accessGroup": 1,
      "type": "site",
      "lang": "",
      "meta": "us",
      "mo": "11",
      "match": "11",
      "hl": "0-2,4-7",
      "weight": 27131,
      "rank": "12",
      "typeName": "Source"
    }
  ],
  "search": "new york",
  "tokens": 4,
  "hits": 2,
  "time(ms)": 0,
  "warnings": "*Default english ordering set",
  "next_offset": "lang:0,media:0,site:52,geo:9,timePeriod:0,ecb_rank:0,ecb_voice:0,ecb_topic:0,ecb_sentiment:0,content:0,rank:0"
}
Example response multiple mode
{
  "lang": {
    "seq": 1,
    "cols": 1,
    "action": "-4",
    "typeName": "Language",
    "suggest": [
      {
        "id": "en",
        "name": "English",
        "url": "",
        "accessGroup": 2147483647,
        "type": "lang",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 723308000,
        "rank": ""
      },
      {
        "id": "es",
        "name": "Spanish",
        "url": "",
        "accessGroup": 2147483647,
        "type": "lang",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 16476000,
        "rank": ""
      },
      {
        "id": "de",
        "name": "German",
        "url": "",
        "accessGroup": 2147483647,
        "type": "lang",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 9752600,
        "rank": ""
      },
      {
        "id": "it",
        "name": "Italian",
        "url": "",
        "accessGroup": 2147483647,
        "type": "lang",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 9737400,
        "rank": ""
      },
      {
        "id": "fr",
        "name": "French",
        "url": "",
        "accessGroup": 2147483647,
        "type": "lang",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 6730800,
        "rank": ""
      }
    ]
  },
  "media": {
    "seq": 2,
    "cols": 1,
    "action": "-32",
    "typeName": "Media Channel",
    "suggest": [
      {
        "id": "575",
        "name": "Web",
        "url": "",
        "accessGroup": 39456725692767,
        "type": "media",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 12711595,
        "rank": ""
      },
      {
        "id": "561",
        "name": "Blog",
        "url": "",
        "accessGroup": 35324227371267,
        "type": "media",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 90014,
        "rank": ""
      },
      {
        "id": "576",
        "name": "Print",
        "url": "",
        "accessGroup": 13401688970945,
        "type": "media",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 79891,
        "rank": ""
      },
      {
        "id": "560",
        "name": "Forum",
        "url": "",
        "accessGroup": 3,
        "type": "media",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 2204,
        "rank": ""
      },
      {
        "id": "577",
        "name": "TV",
        "url": "",
        "accessGroup": 35734465036289,
        "type": "media",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 1060,
        "rank": ""
      }
    ]
  },
  "site": {
    "seq": 3,
    "cols": 1,
    "action": "1208924666693124567859200",
    "typeName": "Source",
    "suggest": [
      {
        "id": "172,330084",
        "name": "New York Post",
        "url": "https://nypost.com",
        "accessGroup": 1,
        "type": "site",
        "lang": "",
        "meta": "us",
        "mo": "11",
        "match": "11",
        "hl": "0-2,4-7",
        "weight": 27131,
        "rank": "12"
      },
      {
        "id": "644",
        "name": "New York Daily News",
        "url": "http://www.nydailynews.com",
        "accessGroup": 1,
        "type": "site",
        "lang": "",
        "meta": "us",
        "mo": "11",
        "match": "11",
        "hl": "0-2,4-7",
        "weight": 13992,
        "rank": "14"
      },
      {
        "id": "23037",
        "name": "The New Yorker",
        "url": "https://www.newyorker.com",
        "accessGroup": 1,
        "type": "site",
        "lang": "",
        "meta": "us",
        "mo": "11",
        "match": "11",
        "hl": "4-6,8-11",
        "weight": 3467,
        "rank": "13"
      },
      {
        "id": "31019",
        "name": "NBC New York",
        "url": "https://www.nbcnewyork.com",
        "accessGroup": 1,
        "type": "site",
        "lang": "",
        "meta": "us",
        "mo": "11",
        "match": "11",
        "hl": "4-6,8-11",
        "weight": 2565,
        "rank": "14"
      }
    ]
  },
  "geo": {
    "seq": 4,
    "cols": 1,
    "action": "1143914305352105984",
    "typeName": "From",
    "suggest": [
      {
        "id": "1372",
        "name": "New York",
        "url": "",
        "accessGroup": 1,
        "type": "geo",
        "lang": "",
        "meta": "",
        "mo": "11",
        "match": "11",
        "hl": "0-2,4-7",
        "weight": 1575336,
        "rank": ""
      },
      {
        "id": "1335",
        "name": "New Jersey",
        "url": "",
        "accessGroup": 1,
        "type": "geo",
        "lang": "",
        "meta": "",
        "mo": "10",
        "match": "10",
        "hl": "0-2",
        "weight": 71500,
        "rank": ""
      },
      {
        "id": "1225",
        "name": "New Zealand",
        "url": "",
        "accessGroup": 1,
        "type": "geo",
        "lang": "",
        "meta": "",
        "mo": "10",
        "match": "10",
        "hl": "0-2",
        "weight": 24987,
        "rank": ""
      },
      {
        "id": "1334",
        "name": "New Hampshire",
        "url": "",
        "accessGroup": 1,
        "type": "geo",
        "lang": "",
        "meta": "",
        "mo": "10",
        "match": "10",
        "hl": "0-2",
        "weight": 11923,
        "rank": ""
      },
      {
        "id": "1336",
        "name": "New Mexico",
        "url": "",
        "accessGroup": 1,
        "type": "geo",
        "lang": "",
        "meta": "",
        "mo": "10",
        "match": "10",
        "hl": "0-2",
        "weight": 11876,
        "rank": ""
      }
    ]
  },
  "timePeriod": {
    "seq": 5,
    "cols": 1,
    "action": "-1024",
    "typeName": "Interval",
    "suggest": [
      {
        "id": "H-12",
        "name": "Last 12 Hours",
        "url": "",
        "accessGroup": 2147483647,
        "type": "timePeriod",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 110,
        "rank": ""
      },
      {
        "id": "d-1",
        "name": "Last 24 Hours",
        "url": "",
        "accessGroup": 2147483647,
        "type": "timePeriod",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 100,
        "rank": ""
      },
      {
        "id": "D",
        "name": "Today",
        "url": "",
        "accessGroup": 2147483647,
        "type": "timePeriod",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 90,
        "rank": ""
      },
      {
        "id": "D-1,D",
        "name": "Yesterday",
        "url": "",
        "accessGroup": 2147483647,
        "type": "timePeriod",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 80,
        "rank": ""
      },
      {
        "id": "d-7",
        "name": "Last 7 Days",
        "url": "",
        "accessGroup": 2147483647,
        "type": "timePeriod",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 70,
        "rank": ""
      }
    ]
  },
  "ecb_rank": {
    "seq": 6,
    "cols": 1,
    "typeName": "ECB Rank",
    "suggest": [
      {
        "id": "449756",
        "name": "Rank 1",
        "url": "",
        "accessGroup": 1,
        "type": "basket213",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 300,
        "rank": ""
      },
      {
        "id": "449754",
        "name": "Rank 2",
        "url": "",
        "accessGroup": 1,
        "type": "basket213",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 200,
        "rank": ""
      },
      {
        "id": "449755",
        "name": "Rank 3",
        "url": "",
        "accessGroup": 1,
        "type": "basket213",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 100,
        "rank": ""
      }
    ]
  },
  "ecb_voice": {
    "seq": 7,
    "cols": 2,
    "action": "-4096",
    "typeName": "ECB Voices",
    "suggest": [
      {
        "id": "454245",
        "name": "Christine Lagarde",
        "url": "",
        "accessGroup": 1,
        "type": "basket215",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 1,
        "rank": ""
      },
      {
        "id": "454791",
        "name": "Luis de Guindos",
        "url": "",
        "accessGroup": 1,
        "type": "basket215",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 1,
        "rank": ""
      },
      {
        "id": "454792",
        "name": "Philip Lane",
        "url": "",
        "accessGroup": 1,
        "type": "basket215",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 1,
        "rank": ""
      },
      {
        "id": "454793",
        "name": "Isabel Schnabel",
        "url": "",
        "accessGroup": 1,
        "type": "basket215",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 1,
        "rank": ""
      },
      {
        "id": "454794",
        "name": "Fabio Panetta",
        "url": "",
        "accessGroup": 1,
        "type": "basket215",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 1,
        "rank": ""
      }
    ]
  },
  "ecb_topic": {
    "seq": 8,
    "cols": 2,
    "action": "-8192",
    "typeName": "ECB Topics",
    "suggest": [
      {
        "id": "449742",
        "name": "Inflation",
        "url": "",
        "accessGroup": 1,
        "type": "basket214",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 1,
        "rank": ""
      },
      {
        "id": "449743",
        "name": "Crypto currencies",
        "url": "",
        "accessGroup": 1,
        "type": "basket214",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 1,
        "rank": ""
      },
      {
        "id": "449744",
        "name": "Monetary policy",
        "url": "",
        "accessGroup": 1,
        "type": "basket214",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 1,
        "rank": ""
      },
      {
        "id": "449745",
        "name": "ECB Events and Publications",
        "url": "",
        "accessGroup": 1,
        "type": "basket214",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 1,
        "rank": ""
      },
      {
        "id": "449746",
        "name": "European Systemic Risk Board",
        "url": "",
        "accessGroup": 1,
        "type": "basket214",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 1,
        "rank": ""
      }
    ]
  },
  "ecb_sentiment": {
    "seq": 9,
    "cols": 1,
    "typeName": "ECB Sentiment",
    "suggest": [
      {
        "id": "459072",
        "name": "Positive",
        "url": "",
        "accessGroup": 1,
        "type": "basket212",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 1,
        "rank": ""
      },
      {
        "id": "459074",
        "name": "Negative",
        "url": "",
        "accessGroup": 1,
        "type": "basket212",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 1,
        "rank": ""
      },
      {
        "id": "459075",
        "name": "Balanced",
        "url": "",
        "accessGroup": 1,
        "type": "basket212",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 1,
        "rank": ""
      },
      {
        "id": "459076",
        "name": "Factual",
        "url": "",
        "accessGroup": 1,
        "type": "basket212",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 1,
        "rank": ""
      }
    ]
  },
  "content": {
    "seq": 10,
    "cols": 1,
    "action": "-67108864",
    "typeName": "Content",
    "suggest": [
      {
        "id": "501",
        "name": "Newspapers",
        "url": "",
        "accessGroup": 2147483647,
        "type": "content",
        "lang": "",
        "meta": "",
        "mo": "10",
        "match": "00",
        "hl": "0-2",
        "weight": 146149197,
        "rank": ""
      },
      {
        "id": "506",
        "name": "Local newspapers",
        "url": "",
        "accessGroup": 2147483647,
        "type": "content",
        "lang": "",
        "meta": "",
        "mo": "10",
        "match": "00",
        "hl": "6-8",
        "weight": 3830388,
        "rank": ""
      },
      {
        "id": "524",
        "name": "Newswire",
        "url": "",
        "accessGroup": 2147483647,
        "type": "content",
        "lang": "",
        "meta": "",
        "mo": "10",
        "match": "00",
        "hl": "0-2",
        "weight": 556998,
        "rank": ""
      },
      {
        "id": "505",
        "name": "City newspapers",
        "url": "",
        "accessGroup": 2147483647,
        "type": "content",
        "lang": "",
        "meta": "",
        "mo": "10",
        "match": "00",
        "hl": "5-7",
        "weight": 162289,
        "rank": ""
      },
      {
        "id": "516",
        "name": "National Newspaper",
        "url": "",
        "accessGroup": 2147483647,
        "type": "content",
        "lang": "",
        "meta": "",
        "mo": "10",
        "match": "00",
        "hl": "9-11",
        "weight": 13524,
        "rank": ""
      }
    ]
  },
  "rank": {
    "seq": 11,
    "cols": 1,
    "action": "-2147483648",
    "typeName": "Rank",
    "suggest": [
      {
        "id": "11",
        "name": "Rank 1",
        "url": "",
        "accessGroup": 2147483647,
        "type": "rank",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 90,
        "rank": ""
      },
      {
        "id": "12",
        "name": "Rank 2",
        "url": "",
        "accessGroup": 2147483647,
        "type": "rank",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 83,
        "rank": ""
      },
      {
        "id": "13",
        "name": "Rank 3",
        "url": "",
        "accessGroup": 2147483647,
        "type": "rank",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 76,
        "rank": ""
      },
      {
        "id": "14",
        "name": "Rank 4",
        "url": "",
        "accessGroup": 2147483647,
        "type": "rank",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 71,
        "rank": ""
      },
      {
        "id": "15",
        "name": "Rank 5",
        "url": "",
        "accessGroup": 2147483647,
        "type": "rank",
        "lang": "",
        "meta": "",
        "mo": "n/a",
        "weight": 66,
        "rank": ""
      }
    ]
  },
  "search": "new york",
  "tokens": 1,
  "hits": 0,
  "time(ms)": 1,
  "warnings": "*Default english ordering set",
  "next_offset": "lang:0,media:0,site:1080,geo:146,timePeriod:0,ecb_rank:0,ecb_voice:0,ecb_topic:0,ecb_sentiment:0,content:18,rank:0"
}

From ids to names

Typically, we want the id of a named entity. But sometimes we would like to go the other way, maybe obtain the name of a site we only know the id of.

This can be done with the getids method: 

https://suggest.api.opoint.com/suggest/<locale>/getids/type:id;type:id

The response is a list of objects of the same format as when searching.